composer.json 的 version 字段仅用于包版本排序和约束解析，不控制 api 兼容性；真正决定兼容性的是 sdk 内部实现、文档约定及用户配置，api 版本应通过请求头、路径或构造参数显式指定。
composer.json 里 version 字段不控制 API 兼容性
很多人以为把 version 写成 "1.2.0" 就能表达“这个 SDK 支持 v1.2 的 API”，其实不是。Composer 只用它做包版本排序和约束解析，完全不管你的代码实际调用的是哪个 API 端点、传什么字段、返回什么结构。
真正决定兼容性的，是 SDK 内部实现 + 文档约定 + 用户怎么用。比如一个叫 acme/api-sdk 的包，version 是 "2.5.1"，但它内部默认请求的是 /v3/users，而你后端只部署了 v2 —— 这时候报错跟 Composer 没半毛钱关系。
-
version只影响require时的语义化版本匹配（如^2.0） - API 版本通常体现在 HTTP 请求头（如
Accept: application/vnd.acme.v2+json）、URL 路径（/api/v2/）或配置参数中 - SDK 应该提供显式的 API 版本切换方式，而不是靠 Composer 版本“暗示”
用 extra 字段声明支持的 API 版本范围
Composer 允许你在 composer.json 里加自定义元数据，extra 是最常用的位置。你可以在这里明确标出这个 SDK 包适配的服务端 API 版本区间，方便下游开发者判断是否匹配。
例如：
{
"name": "acme/api-sdk",
"version": "3.1.0",
"extra": {
"api-version-min": "v2",
"api-version-max": "v3",
"api-version-default": "v3"
}
}
这样做的好处是：工具链可以读取它（比如 CI 脚本校验服务端版本是否在范围内），文档生成器也能自动提取，甚至 IDE 插件未来可据此提示警告。
- 别把
api-version-min/max和 PHP 语言版本混用 —— 它们属于不同维度 - 如果 SDK 同时支持多套不兼容的 API（比如 v1 REST + v2 GraphQL），建议用更细粒度的键，如
"api-flavors": ["rest-v2", "graphql-v1"] - 这个字段对 Composer 安装行为零影响，纯属“说明书”，所以务必同步更新文档和 CHANGELOG
SDK 内部用构造参数或配置项控制 API 版本
用户真正需要的，是一个能直接控制请求行为的入口。硬编码 URL 或 Header 很难维护，也违背向后兼容原则。推荐把 API 版本做成客户端实例化的可选参数。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
比如 PHP SDK 中：
$client = new AcmeClient([ 'base_uri' => 'https://api.example.com', 'api_version' => 'v2' // ← 显式传入，不依赖包版本 ]);
这样用户升级 SDK 包时，只要不改 api_version 参数，行为就不会突变；想尝新 v3，就手动切过去，出问题也容易回滚。
- 不要用常量或全局函数推导版本（如
ACME_API_VERSION），会锁死灵活性 - 如果 SDK 提供 Facade 或静态方法，必须允许覆盖默认版本，否则无法测试多版本兼容逻辑
- 注意：某些旧版 SDK 把版本写死在
Client::BASE_PATH里，这种设计一旦发布就很难补救，重构成本高
遇到 406 Not Acceptable 或 404 时先查请求细节，别急着升 Composer 包
这是最典型的误判场景：API 返回 406 Not Acceptable，用户第一反应是“是不是 SDK 太老了？赶紧 composer update acme/api-sdk”，结果升级后反而更糟——因为新版默认切到了 v3，而你服务端还没上线。
正确排查顺序是：
- 用
curl -v或 Postman 模拟相同请求，确认服务端当前支持哪些版本 - 检查 SDK 实例化时有没有传
api_version，没传就看它的默认值是多少（常藏在Client::__construct()或config.php里） - 翻 SDK 的
CHANGELOG.md，重点看 “Breaking changes” 是否涉及 API 路径或字段变更 - 最后再考虑 Composer 升级 —— 并且升级后要立刻验证你用到的接口是否仍可用
版本管理的本质不是让工具替你做决定，而是给你清晰的控制权和可追溯的行为边界。API 兼容性崩了，90% 的时候不是 Composer 的锅，是 SDK 没暴露够开关，或者你没看清它默认拧在哪个档位上。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
