摘要
1) 一句话总结 本文以 OpenAI 和 Google API 设计中的不一致性为例，阐述了软件系统如何反映组织内部沟通结构（即康威定律），并指出了这些设计缺陷给开发者带来的额外负担。
2) 核心要点
- 康威定律体现：软件设计中的“康威定律”表明，组织设计的系统往往会反映出其内部的沟通结构（交付组织架构图）。
- OpenAI 端点冗余：OpenAI 提供了功能高度相似的
chat/completions（较早）和responses（较新）API，两者均支持生成文本、调用工具和结构化输出。 - 语法不一致：尽管功能相似，这两个端点在实现相同功能（如结构化输出）时，要求使用完全不同的语法格式。
- 文档缺失：OpenAI 官方文档未对端点间的差异和迁移难度做出解释，示例极少且存在错误，开发者被迫通过阅读 Python 包源码来摸索用法。
- Google API 缺陷：Google Gemini API 后端会拒绝合法的 JSON Schema（例如
{"type": "array", "items": {}}）。 - 隐式修复：为解决上述问题，Google 官方 Python 包会在发送请求前，悄悄重写该 schema 以符合后端要求，反映出前后端团队间的潜在脱节。
- 开发者负担：组织为追求快速迭代和频繁发布新功能，往往会遗留大量此类 API 设计上的“小毛病”，将处理成本转嫁给开发者。
3) 风险/不足
- 文档误导风险：OpenAI 官方文档存在错误且缺乏关键说明，可能导致开发者在接入或迁移 API 时受阻。
- 隐式逻辑风险：Google Python 包在底层悄悄重写 JSON Schema，这种不透明的处理方式可能会在复杂场景下引发难以排查的 Bug。
- 开发效率损耗：API 接口设计的不一致和频繁变动，直接增加了外部开发者的学习成本和适配负担。
正文
文档信息
正文
软件设计中有一个被称为“康威定律”（Conway’s Law）的原则：组织所设计的系统，往往会反映出其内部的沟通结构（也就是俗称的“交付组织架构图”）。
OpenAI 有两个功能大体相似的端点（endpoints）：较早的 chat/completions API 和较新的 responses API。（更不用说他们那个更早且现已弃用的 completions 端点了。）
两者都允许你生成文本、调用工具以及生成结构化输出。乍看之下，它们非常相似。但随着深入探究，差异很快就会显现。以结构化输出为例。使用 chat/completions 时，你会这样写：
但对于 responses，则需要写成这样：
我看不出有什么理由非得让它们不一样。这不禁让我怀疑，他们是不是在故意增加从一个端点迁移到另一个端点的难度。而且官方文档对此毫无解释！文档里只有寥寥几个示例，其中至少还有一个是错的。我不得不去阅读他们 Python 包的源代码才弄明白怎么回事。
Google 也存在同样的问题。他们的 Gemini API 会拒绝包含 {"type": "array", "items": {}} 的 JSON Schema（这是一个合法的 schema，表示“包含任意类型元素的数组”）。而他们的官方 Python 包会在发送请求前，悄悄地重写这个 schema 以使其符合要求。我甚至能脑补出这样的画面：Python 包团队的某个人受够了后端团队迟迟不解决这个问题，于是决定自己动手修复。
我承认，对于那些快速迭代、频繁发布新功能的组织来说，这并不奇怪。但这确实给开发者带来了沉重的负担，迫使他们去处理大量诸如此类的小毛病（quirks）。这也不禁让我好奇，这些公司内部到底是个什么情况。
平心而论，我们自己的 API 也存在一些不一致的地方。如果其中任何问题拖慢了你的开发进度，请告诉我们，我们将尽最大努力满足你的需求！