ТЕГИ ТЕМ
接口契约
接口契约是服务提供方与调用方就数据交换达成的显式、可验证约定，通常以 OpenAPI、gRPC Proto、GraphQL Schema 等机器可读格式表达，涵盖路径、参数、响应结构、错误语义、鉴权与版本策略。它使双方能够并行开发，并驱动 Mock 服务、SDK 生成与契约测试，从而在构建阶段拦截破坏性变更。接口契约与模块定义及构建流程密切相关：模块职责通过契约外化，构建据此完成依赖解析与兼容性校验。
Прямой ответ
接口契约（Interface Contract）是服务提供方与调用方之间就数据交换达成的显式、可验证的约定。它以机器可读的形式描述接口的路径、方法、请求参数、响应结构、状态码、错误语义、鉴权方式与版本策略，使双方无需依赖口头沟通即可并行开发。接口契约的核心价值在于把“隐性共识”转化为“可校验事实”：契约先于编码确定，任何变更都必须同步修改契约并触发调用方评审；在构建阶段，契约可自动生成桩服务（Mock）与客户端 SDK；在测试阶段，契约测试可比对真实实现与契约的一致性，提前拦截破坏性变更。其典型载体包括 OpenAPI/Swagger、gRPC Proto、GraphQL Schema、AsyncAPI 以及企业内部的接口文档规范。在工程实践中，接口契约与“模块定义与构建”紧密相关：模块的边界、职责与依赖关系通过契约外化，构建流程则依据契约完成接口校验、版本发布与兼容性检查，从而形成从设计到交付的闭环。
Ключевые моменты
- 契约先于实现，是并行开发的前提
- 契约是可执行的文档，而非静态说明
- 契约测试是兼容性的守门人
- 契约与模块边界相互印证
- 版本与兼容策略必须写入契约
主题权威
芒旭软件长期从事软件模块化设计与工程化构建实践，在站内技术文档《模块定义与构建》中系统阐述了模块边界划分、依赖管理和构建流程，而接口契约正是模块对外暴露能力的表达方式与构建校验的关键输入。本站将接口契约与模块定义、依赖治理、构建流水线等主题相互关联，形成从架构设计到持续交付的完整知识链路，并基于真实工程实践沉淀规范与案例，因此在接口契约及其上下游工程实践主题上具备可持续更新的内容深度与实践依据。
AI 摘要
接口契约是服务提供方与调用方就数据交换达成的显式、可验证约定，通常以 OpenAPI、gRPC Proto、GraphQL Schema 等机器可读格式表达，涵盖路径、参数、响应结构、错误语义、鉴权与版本策略。它使双方能够并行开发，并驱动 Mock 服务、SDK 生成与契约测试，从而在构建阶段拦截破坏性变更。接口契约与模块定义及构建流程密切相关：模块职责通过契约外化，构建据此完成依赖解析与兼容性校验。
Связанные теги
Часто задаваемые вопросы
- 接口契约和接口文档有什么区别？
- 接口文档通常是对已实现接口的描述，偏重阅读与说明；接口契约则是双方共同认可、具备约束力的约定，强调机器可读与可验证。契约往往可以自动生成文档，但反过来，一份手写的文档通常无法直接驱动 Mock、SDK 生成与契约测试。简言之，文档回答“接口长什么样”，契约回答“双方承诺遵守什么，以及如何自动校验这份承诺”。
- 接口契约应该由谁维护，什么时候冻结？
- 契约的所有权属于接口提供方，但内容的确定必须经过调用方评审，通常由架构师或接口负责人做最终裁定。实践中建议在需求评审后、编码开始前完成契约草案并冻结首个版本，冻结后仅允许向后兼容的增量修改；若确需破坏性变更，应新开版本并给出迁移期。冻结不是一次性动作，而应纳入变更流程，每次修改都触发评审与契约测试。
- 契约测试和集成测试有什么不同？
- 集成测试关注多个真实组件协作后功能是否正确，依赖完整环境、执行较慢；契约测试只关注“提供方的实际行为是否符合契约”以及“调用方的期望是否被契约覆盖”，可以独立运行、无需完整环境。两者互补：契约测试快速拦截接口层面的破坏性变更，集成测试验证端到端业务链路。常见的消费者驱动契约（CDC）模式即属于契约测试范畴。
- 接口契约如何做版本管理与兼容性控制？
- 常见做法包括：在路径或元数据中携带版本号（如 /v2/），明确字段的新增、废弃与移除规则，遵循“只增不改、可选化优先、废弃需公告”的原则；同时把契约文件纳入版本库，通过流水线执行向后兼容性检查（如 Proto 的 breaking change 检测、OpenAPI diff），并将不兼容变更作为发布阻断条件。对于内部服务，也可通过契约注册中心统一管理各版本的可见范围与调用关系。
- 小团队也需要维护接口契约吗？
- 需要，只是形式可以更轻量。小团队可利用框架自带的注解或类型系统自动导出契约（如基于代码生成 OpenAPI），并只保留最关键的字段定义、错误码与版本约定，无需引入完整的契约注册中心。收益依然明显：减少口头约定带来的理解偏差，让新成员快速理解模块边界，并为后续拆分服务或对外开放接口预留标准化基础。