为什么 API 设计比代码更长寿
一旦某个 API 被使用，其形态就被固定了。你可以重写其背后的一切代码，但无法随意重命名某个字段，因为旧版本的移动应用可能还在用户手机上运行数年之久。
这种不对称性正是 API 工作应以设计优先的原因。在实施前花一周时间确定合约，能在后续节省更多时间，因为另一种选择是通过版本控制来修复当天做出的决策。
有效的流程
1. 消费者清单
谁会调用这个 API？他们真正需要什么？网页前端、移动应用、合作伙伴集成和内部仪表板有截然不同的需求。移动客户端关注的是有效负载大小和往返次数，而宽带网络上的网页客户端则不然。
2. 先定合约
先编写规范（REST 使用 OpenAPI，GraphQL 使用 schema），并在实施前达成一致。这能带来两个直接好处：前端和后端可基于模拟并行开发，分歧在文档审查阶段暴露，而非在集成测试时。
3. 资源建模
端点应反映业务领域，而非数据库表结构。直接暴露表结构在初期方便，但会变成牢笼：每次模式变更都会导致 API 断裂性变更。
4. 身份认证与权限控制
尽早决定，因为事后修补代价高昂：
- API 密钥：用于服务器对服务器的合作伙伴访问
- OAuth 2.0 / OIDC：用户授权访问其自身数据时使用
- 短期 JWT + 刷新令牌：用于一手应用程序
将权限控制与身份认证分开。知道某人是谁，并不意味着你知道其可查看哪些记录。将两者混为一谈是数据泄露漏洞的常见来源。
5. 错误处理、分页与版本控制
决定 API 是否易于使用的无名英雄：
- 统一的错误格式：包含机器可读的代码和人类可读的消息
- 游标分页：而非偏移分页，确保数据变化时结果保持稳定
- 从第一天开始版本控制：
/v1/现在无成本，日后可避免迁移 - 限流：配备清晰的响应头，让消费者能主动降速，而非被静默切断
6. 文档作为交付成果
生成参考文档并附带实操示例，包括如何认证及常见错误含义。若一名称职的开发者在阅读文档后 20 分钟内无法成功调用 API，则文档尚未完成。
REST 还是 GraphQL？
REST：适用于绝大多数项目。HTTP 缓存有效，调试简单，每位开发者都熟悉，工具链普及。
GraphQL：当你有多个客户端需要不同数据形态，或移动连接上的过度获取（over-fetching）是可衡量成本时使用。它带来真正的复杂性——缓存、查询成本限制、防止深度嵌套查询——必须主动管理。
为单一网页客户端选择 GraphQL 通常是复杂度无回报。为四个客户端各自获取不同子集时选择 REST，则意味着要么创建多个端点，要么浪费大量有效负载。
英国的实际成本
| 范围 | 典型价格区间 |
|---|---|
| 专注型 API，少量资源，认证 | £6,000 – £15,000 |
| 集成已有文档的第三方 API | £2,500 – £6,000 |
| 集成遗留或无文档系统 | £10,000 – £30,000 |
| API 网关、限流、开发者门户 | £8,000 – £20,000 |
值得注意的规律：**集成成本由对方系统驱动，而非你的系统。**现代化且有文档的 API 可能只需一周。无文档的遗留系统、数据不一致且无测试环境，可能耗费一个月。因此我们将其作为限时探索（spike）阶段，而非盲目报价——对未知系统的固定价格报价，最终总有人为此买单。
集成遗留系统
大多数真实项目都不是从零开始的。它们涉及一些旧系统，但这些旧系统仍在支撑业务运行。
如果它有API，预计它会不一致、缓慢，并且以未记录的方式限流。请务必采取防御性措施：使用指数退避重试、熔断器和队列，以确保缓慢的依赖项不会拖垮你的应用。
如果它没有API，按稳健性从高到低的顺序，可选方案包括：定期文件交换（通过SFTP传输CSV或XML）、供应商允许的只读数据库集成，或在受限情况下使用机器人流程自动化（RPA）驱动界面。最后一种方法极其脆弱，供应商一旦更改界面即会中断。若这是唯一途径，我们会实施，同时明确告知你所接受的风险。
**始终添加反腐化层。**在边界处将旧系统的模型转换为你的模型，而不是让其怪异行为蔓延至代码库。这一决策将决定日后替换旧系统是一次项目还是一场灾难。
常见错误
- 将数据库表直接暴露为端点 — 会永久将你的API与数据库模式耦合
- 无版本控制 — 第一次破坏性变更将成为紧急情况
- 认证后置 — 通常意味着每个端点都需重写
- 无限流机制 — 一个编写糟糕的消费者可能使服务对所有人瘫痪
- 错误响应不一致 — 每个消费者都需为每个端点编写定制化处理逻辑
- 文档最后再写 — 结果要么写得很差，要么干脆不写
交付时的优质表现
- 在实施前已确定OpenAPI规范
- 覆盖已记录合约的自动化测试
- 认证与授权作为独立且已测试的模块
- 具备信息性响应头的限流机制
- 结构化日志与错误追踪
- 附带实例的文档
- 可供消费者开发的监控式预发环境
后续步骤
如果你计划进行集成，而另一端的系统情况不明，明智的第一步是进行一项短期付费调研（spike），以确定实际可行性。这通常只需项目成本的一小部分，偶尔还能揭示出你所报价的集成无法按描述构建。
常见问题
一个专注的API，包含少量资源和认证，通常需要£6,000至£15,000。与陈旧或第三方系统集成通常需要£10,000至£30,000，因为大部分成本取决于对方系统而非您的系统。单次完整的第三方集成文档编写约£2,500至£6,000。
大多数情况下选择 REST：更容易缓存、更容易调试，且每位开发者都已熟悉。当多个不同客户端需要相同数据的不同结构，或移动端带宽使得过度获取数据真正成为成本负担时，GraphQL 的复杂性才有其价值。为单一网页客户端选择 GraphQL 通常只会增加复杂性而无实际回报。
专注型 API（包括文档和测试）通常需要 4 到 8 周。集成所需时间几乎完全取决于对端系统的质量——一个设计良好的现代 API 可能只需一周，而一个未记录的遗留系统则可能需要更长时间。这种不确定性应被视为探索性工作（spike）而非猜测，并在项目范围中明确体现。
通常有几种选择：定期文件交换、在允许的情况下通过数据库级别集成，或在受限情况下使用机器人流程自动化。这些方案都不如标准 API 稳健，我们会坦诚告知你这些权衡，而不会将脆弱的方案包装成等效选项。
- API
- integration
- REST
- GraphQL
- architecture