应在 composer.json 中通过 "files" 字段显式声明 IDL 路径（如 "files": ["idl/user-service.thrift"]）或 Composer 2.5+ 的 "include" 配合 glob 模式，确保 IDL 文件被纳入分发包并随 install 复制到 vendor 目录。

composer.json 里怎么声明 IDL 文件位置才不会被忽略

Composer 默认不处理 .thrift 或 .proto 文件，它们不会进 vendor/，也不会随 composer install 自动复制。想让 IDL 成为“可分发包”的一部分，必须显式声明其位置和用途。

常见错误是只在 autoload 里配 PSR-4，结果 IDL 文件根本没被打包进去，下游服务 composer require 后找不到 idl/ 目录。

• 在包的 composer.json 中添加 "files" 字段，明确列出 IDL 路径：

  "files": ["idl/user-service.thrift", "idl/order-service.thrift"]

• 或用 "include"（需 Composer 2.5+）配合 glob：

  "include": ["idl/**/*.thrift"]

• 确保 IDL 文件在 Git 提交范围内 —— composer install 只复制已 tracked 的文件
• 避免用 extra 字段存路径，那只是元数据，不触发文件复制

如何让下游服务自动加载并验证 IDL 内容

单纯把 .thrift 文件放进包里还不够。下游服务需要能读、能校验、能生成代码，而不是手动去 vendor/acme/user-service/idl/ 找文件。

推荐做法是封装一个轻量级 PHP 工具类，随包一起发布：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

• 提供 AcmeIDLLoader::load(string $name): string 方法，按服务名返回对应 IDL 内容（路径由包内 files 定义决定）
• 内置 ThriftCompiler::validate()，调用系统 thrift --gen php 做语法检查（失败时抛 InvalidIDLException）
• 在 composer.json 的 "autoload" 中注册该类所在的命名空间，确保能被自动加载
• 不要在 require-dev 里放 apache/thrift —— 验证逻辑是运行时契约的一部分，应进 require

私有仓库中 IDL 包的版本约束为什么不能用 dev-main

CI 构建时频繁报 Failed to clone https://git.example.com/acme/user-idl，90% 是因为用了 "dev-main" 这种不稳定版本约束。

原因很直接：Composer 在 CI 环境下默认禁用 Git clone（出于安全与性能），而 dev-main 强制走 clone 流程，不是从 dist 下载归档。

• 必须打语义化 tag（如 v1.0.0、v1.1.0），并在下游 composer.json 中写 "acme/user-idl": "^1.0"
• 私有 Satis 或 Toran Proxy 仓库必须开启 archive 功能，确保每个 tag 对应 zip/tar.gz 归档
• 本地开发调试可用 "repositories" + "path" 类型临时指向本地目录，但上线前必须删掉或注释掉
• CI 脚本中禁止出现 composer update —— 它会重写 composer.lock，导致 IDL 版本意外升级

IDL 自动生成代码后如何避免命名空间冲突

多个微服务都 require 同一个 IDL 包，各自执行 thrift --gen php 生成客户端代码，结果所有服务都往 src/ 写 UserServiceClient.php，最后 autoload 冲突。

根本解法不是改生成路径，而是让生成动作脱离应用代码树：

• IDL 包自身不生成任何 PHP 类，只提供原始 .thrift 和验证工具
• 各微服务在 post-install-cmd 脚本中调用 thrift --gen php -o ./generated/ ...，把代码输出到 generated/ 目录
• 在服务自己的 composer.json 中配置：

  "autoload": {"psr-4": {"App\Generated\": "generated/"}}

• 确保 generated/ 不进 Git —— 它是构建产物，由 CI 生成并缓存
• 若用 Docker，把 thrift 二进制打进基础镜像，避免每次构建都下载

真正难的不是让 IDL 被分发，而是让每个服务对同一份 IDL 的理解保持一致 —— 这要求版本号、验证逻辑、生成路径、autoload 映射全部收敛到可审计的配置项里，而不是靠人肉同步。