API 设计原则

RESTful API 与 RPC API 对比

在 API 设计领域，常见的两种架构风格：

典型的 RPC 风格接口包括：

• CORBA
• SOAP
• gRPC

RPC API 通常围绕 操作（Operation） 进行设计。

API 表示客户端可以调用的动作。

示例：

CreateUser()

GetUserInfo()

TransferMoney()

GenerateReport()

客户端需要了解：

这种方式通常：

• 与具体业务场景高度绑定
• 强依赖客户端和服务端约定
• 难以扩展成开放平台 API

REST 关注的是 资源（Resource） ，而不是操作。

资源通过 URI 标识，并通过标准 HTTP 方法进行操作。

示例：

GET /users/123

DELETE /users/123

API 描述的是：

系统提供什么资源，而不是内部如何实现。

RESTful API 的优势

降低系统耦合

REST API 降低客户端和服务端之间的依赖。

客户端只需要理解：

• 资源模型
• URI 结构
• HTTP 语义

服务端内部实现可以独立演进。

Client

    |
    |
    v

GET /users/100

    |
    |
    v

User Service

客户端不关心后端使用：

• SQL Server
• PostgreSQL
• MongoDB

面向平台的 API

REST API 更适合作为服务生态的平台基础。

核心服务提供通用能力：

/users

/orders

/products

这些 API 可以支持：

• Web 应用
• 移动应用
• 内部服务
• 外部合作伙伴

REST API 设计原则

优先使用 REST + JSON

推荐：

HTTP + REST + JSON

请求：

{
  "name": "Tom",
  "age": 30
}

响应：

{
  "id": 1001,
  "name": "Tom"
}

简单开始，逐步演进

REST API 不需要一开始就达到最高成熟度。

Richardson 成熟度模型：

实际推荐：

从简单 REST API 开始，根据业务需求逐步演进。

Postel 鲁棒性原则

原则：

中文：

对输入保持开放，对输出保持谨慎。

接收未知字段

接收客户端数据时：

API 应该忽略未知字段，而不是直接失败。

客户端发送：

{
  "name": "Tom",
  "age": 30,
  "nickname": "Tommy"
}

服务端只支持：

{
  "name": "Tom",
  "age": 30
}

服务端可以忽略：

nickname

优势：

• 向前兼容
• API 独立演进
• 降低客户端与服务端依赖

返回最小数据

API 不应该默认返回大量无关数据。

错误：

{
  "id":100,
  "name":"Tom",
  "orders":[],
  "history":[],
  "settings":{}
}

更好的方式：

{
  "id":100,
  "name":"Tom"
}

额外数据通过参数获取：

GET /users/100?include=orders

API 即产品

API 不应该只是系统内部接口。

应该：

将 API 当作产品。

API 产品原则

像产品负责人一样思考

关注：

• 客户需求
• 开发者体验
• 易用性

避免：

Backend implementation convenience

而应该关注：

Client developer experience

长期维护一致性

优秀 API 应具备：

• 命名一致
• 行为可预测
• 契约稳定

推荐：

GET /users

GET /orders

GET /products

避免：

GET /getUserList

POST /createOrderData

API 优先

API First 的核心：

在编码之前先定义 API。

传统方式：

Code

↓

Expose API

↓

Ask feedback

Design API

↓

Review

↓

Implement

↓

Test

8. API First 要求

8.1 API 规范优先

使用标准规范定义 API：

OpenAPI Specification

优势：

• API 文档
• 客户端 SDK 生成
• 自动化验证
• API 发现

提前 Review

API 应该由：

• 团队成员
• 架构评审人员
• 客户端开发者

在开发前进行评审。

9. API First 的收益

单一事实来源

API 定义成为双方契约：

• 服务提供方
• API 消费者

openapi.yaml

分离 WHAT 与 HOW

API 应该定义：

WHAT

而不是：

HOW

POST /orders

表示：

创建订单。

不应该暴露：

Save database record

Call internal service

Send message queue event

实现可以变化。

API 应保持稳定。

10. API First 与敏捷开发

API First 并不意味着：

不是：

完全设计好所有 API 后才能编码。

API 同样需要迭代。

典型流程：

Draft API

↓

Internal Review

↓

Implementation

↓

Feedback

↓

API Evolution

总结

RESTful API 设计目标：

构建简单、一致、稳定、易用，并且可以长期演进的 API 平台。