Composer中文规范并非官方概念，而是团队基于composer.json字段命名、包命名空间、版本约束等制定的本地约定，核心是确保API版本与包版本严格绑定，避免目录混用导致类冲突与加载失效。
Composer 中文规范到底指什么？别被名字骗了
Composer 本身没有“中文规范”这个官方概念，所谓“中文规范”通常是团队内部对 composer.json 字段命名、包命名空间、版本约束写法、changelog 格式等做的本地约定。比如强制要求 name 字段用 vendor/cn-package-name 格式，description 必须是中文，version 不允许直接写死而必须走 git tag + dev-main 别名。这些不是 Composer 的限制，而是你自己的发布管道（CI/CD）在 composer validate 后额外加的校验脚本。
真正影响 API 版本化分发的是三件事：包命名是否支持语义化隔离、版本号如何映射到 Git 分支/tag、以及用户能否通过 require 精确拉取指定 API 版本。其他所谓“中文规范”只是增加校验成本，不解决分发本质问题。
API 版本必须绑定到 Composer 包版本，不能靠目录或子路径
常见错误是把不同 API 版本放在同一包的 /src/v1、/src/v2 目录下，然后靠运行时判断版本路由。这会导致：composer install 总是拉全量代码，v1 用户被迫加载 v2 的类；PHP 自动加载器无法隔离版本间类冲突；patch 版本更新（如 v1.0.1 → v1.0.2）可能意外破坏 v2 的行为。
正确做法是每个主版本对应独立包：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
myorg/api-sdk-v1对应^1.0，只含 v1 接口和 DTO -
myorg/api-sdk-v2对应^2.0，完全独立实现，不依赖 v1 包 - 所有包共享同一 Git 仓库，但用
git subtree或splitsh拆出各自composer.json和源码树 - CI 在打 tag
v1.2.3时，自动发布到私有 Packagist（如 Satis 或 Private Packagist），并确保composer require myorg/api-sdk-v1:^1.2能精准命中
私有 Packagist 必须支持 stability flags 和 branch-alias
内部系统常忽略稳定性标记导致依赖解析失败。例如，开发阶段用 dev-main 测试新 API，但 composer require myorg/api-sdk-v2:dev-main 会报错，除非你在私有仓库配置中显式允许 minimum-stability: dev，且包自身声明 "minimum-stability": "dev" 或在 composer.json 中写 "branch-alias": {"dev-main": "2.x-dev"}。
关键配置点：
- Satis 配置里加
"require-dependencies": true，否则跨包依赖（如 v2 包依赖公共工具包）不会被索引 - 每个包的
composer.json必须有明确type（如library），否则某些私有仓库前端不显示 - 禁止用
path仓库类型上线——它绕过版本解析，导致composer update行为不可预测 - 所有 tag 必须符合
v{MAJOR}.{MINOR}.{PATCH}格式，否则^2.0这类约束无法匹配
客户端 require 时最容易漏掉的两个约束条件
业务方写 composer require myorg/api-sdk-v2 看似没问题，但实际会拉最新 dev-main 或最高 stable 版，而非你期望的 2.3.0。必须强制约定：
- 所有项目
composer.json的config段加"preferred-install": "dist"，避免因源码安装导致分支别名失效 - require 语句必须带版本约束：
composer require myorg/api-sdk-v2:^2.3，而不是裸包名 - 若用 monorepo 工具（如 Lerna 类似物），需确认其生成的
composer.json是否清除了repositories字段——私有仓库地址丢失会导致 fallback 到 packagist.org 找不到包
版本号不是装饰品，它是 Composer 解析依赖图的唯一坐标。任何试图用文档、目录结构或运行时开关替代它的方案，迟早会在 composer update 时暴露。
