自定义API开发：流程与成本

API 设计比代码更持久

一旦某个系统开始消费您的 API，其结构就几乎固定了。您可以重写其背后的所有内容，但无法随意更改一个移动应用程序依赖的字段名称，因为旧版本的应用程序可能会在用户手机上运行多年。

这种不对称性就是为什么 API 工作应该从设计开始的原因。在实现前花一周时间商定合约，可以节省后续大量时间，因为如果在下午做出的决定需要通过版本迭代来解决，代价会非常高。

实际有效的流程

1. 消费者清单

谁会调用这个 API，以及他们实际需要什么？网页前端、移动应用、合作伙伴集成和内部仪表盘有着完全不同的需求。移动客户端对负载大小和往返次数的关注程度，与宽带网络上的网页客户端不同。

2. 合约优先

编写规范（REST 使用 OpenAPI，GraphQL 使用模式），并在实现前达成一致。这会带来两个直接好处：前端和后端可以并行开发，基于模拟数据进行工作，并且争议会在文档审查阶段浮现，而不是在集成测试中。

3. 资源建模

端点应反映业务领域，而不是数据库表结构。直接暴露表结构虽然一开始方便，但最终会成为一个限制：每次模式变更都会导致 API 的破坏性变更。

4. 认证与授权

尽早决定，因为事后补救会非常痛苦：

• API 密钥，用于服务器到服务器的合作伙伴访问
• OAuth 2.0 / OIDC，用于用户授权访问自身数据
• 短期 JWT 与刷新令牌，用于第一方应用

同时保持授权与认证的独立性。知道某人是谁并不意味着知道他们可以看到哪些记录，混淆这两者是数据泄露的常见原因。

5. 错误处理、分页、版本控制

这些不太引人注目的部分决定了 API 是否易于开发：

• 统一的错误格式，包含机器可读的代码和人类可读的消息

• 基于游标的分页，而不是偏移量，以保持结果稳定，即使数据发生变化

• 从第一天开始版本控制 —— /v1/ 现在成本为零，但可以避免后续迁移

• 速率限制，带有清晰的头信息，以便消费者可以主动减少请求，而不是被静默切断

• 统一的错误结构，包含机器可读的代码和人类可读的消息

• 基于游标的分页，而不是偏移量，以保持结果稳定，即使数据发生变化

• 从第一天开始版本控制 —— /v1/ 现在成本为零，但可以避免后续迁移

• 速率限制，带有清晰的头信息，以便消费者可以主动减少请求，而不是被静默切断

6. 文档作为交付成果

生成的参考文档加上实际示例，包括如何进行认证以及常见错误的含义。如果一位熟练的开发者无法在阅读文档二十分钟后完成一次成功的调用，那么文档就没有完成。

REST 还是 GraphQL

REST 适用于大多数项目。HTTP 缓存有效，调试简单，每个开发者都熟悉它，且工具链通用。

GraphQL 适用于多个不同客户端需要不同形状的同一数据，或者在移动连接中过度获取数据会带来可测量成本的情况。它引入了真正的复杂性——缓存、查询成本限制、防止深度嵌套查询——这些都需要主动管理。

为单一网页客户端选择 GraphQL 通常意味着增加复杂性而无回报。而当有四个客户端各自获取不同子集数据时，选择 REST 则意味着要么创建多个端点，要么承受大量冗余负载。

在英国的实际成本

范围	典型价格范围
集中式 API，少量资源，认证	£2,400 – £6,000
与已文档化的第三方 API 集成	£1,000 – £2,400
与遗留系统或未文档化系统集成	£4,000 – £12,000
API 网关、速率限制、开发者门户	£3,200 – £8,000

需要注意的是：集成成本主要由其他系统决定，而不是您的系统。 一个现代且已文档化的 API 可能只需要一周时间。而一个未文档化的遗留系统，数据不一致且没有测试环境，可能会耗费一个月的时间。这就是为什么我们会将这些工作定义为时间有限的探索阶段，而不是直接报价——在未知系统上报固定价格，最终可能会由某人来承担风险。

集成遗留系统

大多数实际项目并非从零开始。它们通常涉及一些旧系统，但仍在运行业务。

如果它有一个API，预计它会存在不一致、缓慢，以及未记录的速率限制问题。因此，应采取防御性措施：实现指数退避的重试机制、熔断器，以及一个队列，以防止慢速依赖将您的应用程序拖垮。

如果它没有API，可行的解决方案按鲁棒性从高到低排列如下：定期文件交换（通过SFTP传输CSV或XML文件）、在供应商允许的情况下进行只读数据库集成，或者在受限情况下，通过机器人流程自动化驱动界面。后者确实非常脆弱，每当供应商更改界面时都会出现问题。如果这是唯一可行的路径，我们将实施它，但会明确说明您正在接受的风险。

总是添加防腐层。在边界处将遗留系统的模型翻译成您自己的模型，而不是让其怪癖在代码库中蔓延。这一决定将决定未来是否能够顺利替换遗留系统，而不是变成一场噩梦。

常见错误

1. 将数据库表暴露为端点 —— 永久耦合API与数据库架构
2. 无版本控制 —— 第一个破坏性变更将成为紧急事件
3. 事后添加身份验证 —— 通常意味着需要重写每个端点
4. 无速率限制 —— 一个编写不当的消费者会导致服务对所有人停止运行
5. 错误信息不一致 —— 每个消费者需要为每个端点编写定制的处理逻辑
6. 文档最后才写 —— 因此文档要么写得不好，要么根本没有

交付时的优秀标准

• 在实施开始前达成OpenAPI规范
• 自动化测试覆盖文档化的合约
• 身份验证和授权作为独立且经过测试的功能
• 带有信息性头部的速率限制
• 结构化日志和错误跟踪
• 带有示例的文档
• 消费者可以用于开发的监控预发环境

下一步

如果您计划进行集成，而另一端的系统情况不明，明智的第一步是进行一项短期付费的探索性工作（spike），以明确实际可行的内容。这通常只需项目成本的一小部分，偶尔还会发现您最初被报价的集成无法按照描述的方式构建。