Composer 不能锁接口契约版本，因其仅管理 PHP 包实现而非 API 定义；契约需通过 OpenAPI 文件+openapi-generator-cli 在 post-install-cmd 中生成代码，并用 git submodule 锁定 YAML 版本。
为什么 composer require 不能直接锁下游服务的接口契约版本？
因为 Composer 管理的是 PHP 包（vendor 里的实现），不是 API 接口定义。你装的 acme/payment-sdk 是个 SDK，它内部可能封装了对 /v1/charge 的调用，但这个接口的请求结构、字段含义、错误码，不归 Composer 管——它只管“这个 SDK 的 PHP 类有没有 createCharge() 方法”。
Contract-first 的核心是：先有 OpenAPI/Swagger 文件或 Protobuf IDL，再生成客户端/服务端骨架。Composer 对这类契约文件本身没有解析或校验能力。
- 常见错误现象：
composer update后下游服务悄悄升级了 API 字段（比如把amount_cents改成amount），SDK 却没同步更新，网关调用直接 400 或字段丢失 - 使用场景：多个下游服务（支付、用户、订单）各自维护自己的 OpenAPI v3 YAML，网关项目需统一拉取、校验、生成 DTO 和 client
- 根本原因：Composer 不处理契约文件，只处理
composer.json中声明的包版本
怎么用 composer-scripts + openapi-generator-cli 在 install/update 时自动拉取并生成契约代码？
把契约当作“构建依赖”，而不是“运行时依赖”。用 Composer 的脚本钩子，在 post-install-cmd 和 post-update-cmd 触发本地契约同步流程。
- 在
composer.json的"scripts"里加："post-install-cmd": [ "cd ./contracts && git pull origin main", "openapi-generator-cli generate -i ./contracts/payment.yaml -g php -o ./src/Client/Payment --additional-properties=packageName=PaymentClient" ]
- 确保
openapi-generator-cli已全局安装：npm install @openapitools/openapi-generator-cli -g - 所有
.yaml契约文件必须放在项目内固定路径（如./contracts/），不能靠require拉远程 Git 包——Composer 不会帮你 checkout 子目录下的 YAML - 生成的 PHP 客户端代码要加进
autoload，否则new PaymentClient\Api\ChargeApi()会找不到类
composer.lock 能否锁定 OpenAPI 文件的 Git commit hash？
不能直接锁。但可以间接实现：把契约仓库作为子模块（git submodule）或用 make sync-contracts 脚本固化 commit。
- 推荐做法：在项目根目录执行
git submodule add -b main https://git.example.com/contracts.git contracts - 这样
composer install后，运行git submodule update --init --recursive就能精准检出某次 commit 的 YAML - 检查是否生效：
git submodule status contracts输出类似+a1b2c3d (heads/main)，开头的+表示当前 commit 不在父仓库记录中——这时就得git add contracts && git commit把它写进composer.lock的等效位置 - 陷阱：如果用
https地址且没配 token，CI 环境可能拉不下 submodule；改用 SSH 或预配置git config --global url."git@github.com:".insteadOf "https://github.com/"
下游服务改了 OpenAPI，网关如何提前发现不兼容变更？
靠生成代码时的报错不够——OpenAPI Generator 默认容忍很多变化。得加一层语义校验。
- 用
openapi-diff工具比对前后两个 YAML：openapi-diff old.yaml new.yaml --fail-on-breaking - 把这个命令塞进 CI 的 pre-commit 或 PR 检查环节，失败就阻断合并
- 重点关注：
required字段变可选、状态码删除、路径参数类型从string改成integer——这些才是真 breaking change - 别依赖 SDK 版本号：下游可能发了个
v2.1.0，但只改了文档 typo，实际接口没动；也可能发v2.0.1却删了关键字段——版本号和契约变更不严格对应
契约不是写完就扔在文档站里的静态文件，它是网关与下游之间最硬的接口协议。每次 git pull contracts 后，真正要确认的不是“文件下载成功”，而是“生成的 DTO 属性名、必填性、嵌套结构，和下游当前线上环境完全一致”。这点容易被跳过，尤其当本地跑通、测试也过，就直接上线了。
