API 设计最佳实践：RESTful、GraphQL 与 gRPC 的选型策略与对比

没有银弹

RESTful、GraphQL、gRPC 各有优劣。技术选型的核心不是追求"最好"，而是找到"最合适"的方案。

1. RESTful API

// 最佳实践
GET    /api/v1/users          # 列表（支持分页、筛选、排序）
GET    /api/v1/users/:id      # 单个资源
POST   /api/v1/users          # 创建
PUT    /api/v1/users/:id      # 全量更新
PATCH  /api/v1/users/:id      # 部分更新
DELETE /api/v1/users/:id      # 删除

// 分页规范
GET /api/v1/users?page=1&per_page=20&sort=-created_at
→ { data: [...], meta: { current_page: 1, total: 150, per_page: 20, total_pages: 8 } }

2. GraphQL

type Query {
    user(id: ID!): User
    posts(page: Int!, limit: Int!): PostConnection!
}

type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!  # 关联查询
}

# 前端按需查询
query {
    user(id: "123") {
        name
        posts(limit: 5) {
            title
            createdAt
        }
    }
}

3. gRPC

// user.proto
syntax = "proto3";
package user;

service UserService {
    rpc GetUser (GetUserRequest) returns (User);
    rpc ListUsers (ListUsersRequest) returns (stream User);  // 流式响应
}

message GetUserRequest {
    int64 id = 1;
}

message User {
    int64 id = 1;
    string name = 2;
    string email = 3;
}

4. 全方位对比

维度	RESTful	GraphQL	gRPC
传输协议	HTTP/1.1	HTTP/1.1	HTTP/2
数据格式	JSON/XML	JSON	Protobuf(二进制)
类型安全	弱（靠文档）	强（Schema）	强（Proto）
学习曲线	低	中	高
性能	中	中	高（比 JSON 快 5-10x）
打包体积	大	中	小（二进制）
浏览器支持	原生	原生	需 gRPC-Web
适合场景	通用 Web API	复杂数据查询	微服务间通信

5. 选型决策树

对外公开的 Web API → RESTful（简单通用）
前端需要灵活的数据聚合 → GraphQL（按需获取）
内部微服务间高性能通信 → gRPC（低延迟、强类型）
移动端 + API 版本管理复杂 → GraphQL（Schema 演进）
实时流式数据传输 → gRPC（原生支持 streaming）

总结

三种范式不是互斥的。大型系统常见的是 RESTful（外部）+ gRPC（内部）的组合。理解各自优劣，才能做出正确的架构决策。