定制软件接口契约怎么写
两套系统交换数据之前，接口契约写明路径或消息种类、必填栏、身份验证、错误码、版本，以及不兼容的改动要谁点头。需求规格写的是做完之后业务上什么算达成；验收和用户验收写的是画面上怎样把那一条做出来；这一页写的是两边系统互相调用时，栏位和错误怎样对得上。
目录
接口契约和需求规格、验收分开写
需求规格回答的是哪一个角色在哪一个画面完成哪一件事、谁对那一条负责、这一版明确不做什么。验收标准回答的是示范时旁人看得到什么。用户验收回答的是那一条的负责人是否自己做过，或在场看完。接口契约回答的是另一件事：这一边送出的一笔，另一边按哪一条路径或哪一种消息收下，缺了哪一栏就算没送到，身份验证不过或处理失败时回哪一个码。四份可以指到同一次交换的名称。规格里的达成状态不改写成路径，验收清单也不把错误码当成画面上的一句文案来勾。分别见 定制软件需求规格怎么写、定制软件验收标准怎么写、定制软件 UAT 怎么做。
范围变更管的是规格要不要改、谁可以收下修改。见 定制软件范围变更怎么管。交付仍走 定制软件、网站与应用程序。另一边若是现场设备而不是另一套业务画面，栏位仍写在这份契约，设备怎样接到既有系统另见 设备怎么接到既有业务系统。契约封面写自己的版本、两边系统的名称，以及存放路径。
路径或消息种类先有名字
2026年10月28日阅读的 OpenAPI Specification 3.1.2 页首写明版本日期为 2025年9月19日。该页写明，OpenAPI Specification 定义一套与编程语言无关的接口描述，用来说明 HTTP API，让人和计算机不必读源代码、不必另找文件、也不必查看网络流量，就能了解服务能做什么。该页并写明，一份 OpenAPI Description 至少要有 paths、components 或 webhooks 其中之一。Paths Object 放的是各个端点的相对路径及其操作；路径接到 Server Object 的 URL 后面，组成完整网址。路径栏位的名称必须以斜线开头。
同一页写明，Operation Object 描述路径上的单次操作，可以包含参数、请求本体、回应，以及该次操作使用的身份验证。交换若不是由调用方发起的 HTTP，该页的 webhooks 用一个不重复的键名指到每一则 webhook，并用 Path Item 描述由 API 提供方发起的请求和预期回应。队列或文件交换若对不上这两种写法，契约仍为每一种消息写一个不重复的名称，并在封面注明它不是该页的 path 或 webhook。没有名称的交换不进契约。该页的宠物店例子只说明格式，不拿来当项目的路径。
必填栏写在结构里
同一份 OpenAPI 3.1.2 写明，Schema Object 是 JSON Schema Draft 2020-12 的超集；除非另有说明，关键字的定义沿用 JSON Schema。2026年10月28日阅读的 JSON Schema Validation 是 Internet-Draft draft-bhutton-json-schema-validation-01，页首写明发表于 2022年6月16日、于 2022年12月18日到期、预期状态为 Informational，作者为 A. Wright、H. Andrews、B. Hutton。该草案对 required 的写法是：它的值必须是数组，元素必须是字符串且不得重复；一个对象要算通过，数组里的每一项都必须是该对象的属性名称；省略这个关键字，效果与空数组相同。
契约里的请求或回应若有必填栏，就把栏名放进该结构的 required。栏名没有写进这一数组，依该草案就不算必填，接收方不能事后把空值说成对方漏送。公司自己的必填名单写在契约上并注明日期；草案没有替项目列出栏名。参数若在路径上，OpenAPI 写明该参数的 required 必须为 true。选填栏可以出现在结构里，但不放进 required。金额、单号、状态这一类名字，以两边已经在用的栏名为准，不在契约里另起一个只给文件看的别名。
身份验证写明用哪一种
OpenAPI 3.1.2 的 Security Scheme Object 写明可用的方案包括 HTTP 验证、API 密钥（放在请求头、cookie 或查询参数）、相互 TLS、OAuth 2.0 在 RFC 6749 里的几种常见流程，以及 OpenID Connect。type 的有效值为 apiKey、http、mutualTLS、oauth2、openIdConnect。该页并写明，以 2020 年而言，implicit 流程即将被 OAuth 2.0 Security Best Current Practice 标为不建议；多数情况建议使用带 PKCE 的授权码流程。这是该页对方案的列举和建议，不是要求这次交换必须采购某一种产品。
契约选一种写进 security，并写明键名落在请求头、cookie 还是查询参数。整份 API 的 security 可以被单次操作覆写；该页写明，空数组表示拿掉上层的验证宣告。没有写 security、也没有写明这次交换故意不验证，接收方不依口头约定放行。凭证何时更换写在公司自己的维运记录，契约只写方案种类和键名。密码、令牌和私钥不贴进契约正文。
错误写回应码和这一次的意思
同一份规范的 Responses Object 把 HTTP 回应码对到预期回应。该页写明，文件不必涵盖所有可能的回应码，因为事先未必知道；但仍预期写出成功时的回应，以及已知的错误。Responses Object 必须至少有一个回应码；若只写一个，应该是成功调用的回应。回应码应从 IANA Status Code Registry 里已登记的码挑选。default 可以用来说明未被逐码写出的回应。
契约为这一次交换写下成功时的码，以及已知错误的码。每一个码配一段说明，写这一次失败时对方看得到什么，而不是只重复该码的通用名称。尚未遇过的错误不预先编一个项目专用的数字；未列出的码走 default，说明写「契约未列」。登记册没有的自定码不写进这一栏。成功和已知错误都还没写，这一条操作不算写完。
文件版本和接口版本分开
OpenAPI 的 info.version 是必填。该页写明，它是 OpenAPI Document 的版本，并与规范本身的版本、所描述 API 的版本，以及 OpenAPI Description 的版本都不是同一件事。openapi 栏位则是这份文件使用的规范版本，该页写明它和 info.version 无关。契约封面若只填了 info.version，旁边要注明它是文件版本还是接口版本；两个都要时分成两栏。
2026年10月28日阅读的 Semantic Versioning 2.0.0 该页没有刊登日期，作者为 Tom Preston-Werner。摘要写明，版本号 MAJOR.MINOR.PATCH 之中，做了不兼容的 API 改动就递增 MAJOR，以向后兼容的方式增加功能就递增 MINOR，向后兼容的错误修正就递增 PATCH。规范第 1 条写明，使用这套版本的软件必须宣告一份公开 API。第 8 条写明，只要公开 API 出现向后不兼容的改动，MAJOR 就必须递增。公司若采用这套编号，在契约封面写明，并把公开 API 指到这一份契约，而不是指到尚未写完的会议记录。
不兼容的改动要先有人点头
SemVer 第 3 条写明，某个版本一旦发布，该版本的内容不得再改；任何修改都必须作为新版本发布。第 8 条把向后不兼容的改动放在 MAJOR。该页关于停用的问答写明，停用公开 API 的一部分时应做两件事：更新文件让使用方知道，并发行一个带着这项停用的 MINOR；在下一个 MAJOR 完全移除之前，至少要有一个包含停用的 MINOR，使用方才有办法转过去。OpenAPI 把操作的 deprecated 设为 true 时，该页写明使用方应该停止使用该操作，默认值是 false。
谁可以点头让不兼容的改动进入下一版，写在契约封面，注明姓名和同意日期。SemVer 没有指定这个人。没有这一行，路径、必填栏或错误码的不兼容改动不发布给另一边。文件可以先改，调用仍停在上一版，直到这个人签过。范围变更那一篇管的是业务规格，不代替这一行签名。公司若采用 SemVer，签名之后 MAJOR 才递增，旧版依第 3 条不再被原地改写。未采用 SemVer 的，仍要换上一条与旧版不同的接口版本字符串，并在封面写明编号办法。
名称、必填栏、验证、错误和版本写上，才算这份契约
路径或消息种类没有名称、必填栏没有放进 required 或没有注明这一笔没有必填、身份验证方案空白、成功回应码还没有、接口版本还没有和文件版本分开，这一条都不进双方可以调用的清单。口头说先对着测试环境打，不补上这些栏。
用三件事看这份契约能不能给另一边用：每一条交换都有路径或消息名称、必填栏和已知错误码写在同一条、不兼容的改动有负责人和同意日期。有一项空着，这一条留在草稿，另一边不按它上线。