API 风格

这一课你将能做到

1. 对比 REST、GraphQL、gRPC、WebSocket 四种 API 风格的优缺点，并给出选型建议
2. 用 GraphQL 实现一个灵活查询的课程接口，理解 Schema 和 Resolver
3. 用 WebSocket 实现实时通知，理解长连接与轮询的区别

为什么要学

REST 不是银弹。当「前端需要的数据嵌套很深」「移动端要省流量」「微服务之间要高性能通信」「需要实时推送」时，REST 要么啰嗦要么做不到。知道每种风格的适用场景，才能在该用 REST 时用 REST，该换技术时敢换。

先建立图像

四种风格对比：

┌──────────┬─────────────┬─────────────┬─────────────┬─────────────┐
│          │    REST     │   GraphQL   │    gRPC     │  WebSocket  │
├──────────┼─────────────┼─────────────┼─────────────┼─────────────┤
│ 协议      │ HTTP/1.1    │ HTTP/1.1    │ HTTP/2      │ TCP 长连接  │
│ 数据格式  │ JSON        │ JSON        │ Protobuf    │ 自定义      │
│ 契约      │ 弱（靠文档） │ 强（Schema）│ 强（.proto）│ 弱          │
│ 查询方式  │ 固定端点    │ 客户端指定  │ 固定方法    │ 事件驱动    │
│ 实时性    │ 轮询/SSE    │ 轮询/订阅   │ 流式        │ 原生实时    │
│ 适用场景  │ 通用 CRUD   │ 复杂查询    │ 微服务内部  │ 实时通信    │
└──────────┴─────────────┴─────────────┴─────────────┴─────────────┘

跟着做

步骤 1：REST 的局限

场景：前端需要「课程详情 + 讲师信息 + 最新 5 条评价」

REST 方案（3 次请求）：

curl /api/lessons/123
curl /api/instructors/456
curl /api/lessons/123/reviews?limit=5

或者做一个聚合端点（后端耦合）：

curl /api/lessons/123/detail

问题：要么多次请求（慢），要么后端为每个前端页面定制接口（耦合）。

步骤 2：GraphQL 方案

# Schema 定义
type Lesson {
    id: ID!
    title: String!
    content: String!
    instructor: Instructor!
    reviews(first: Int): [Review!]!
}

type Instructor {
    id: ID!
    name: String!
    avatar: String
}

type Review {
    id: ID!
    content: String!
    rating: Int!
    author: User!
}

type Query {
    lesson(id: ID!): Lesson
}

# 客户端查询：一次请求拿所有数据
query {
    lesson(id: "123") {
        title
        content
        instructor {
            name
            avatar
        }
        reviews(first: 5) {
            content
            rating
            author {
                name
            }
        }
    }
}

// Spring Boot + GraphQL
@Controller
public class LessonGraphQLController {

    @QueryMapping
    public Lesson lesson(@Argument String id) {
        return lessonService.findById(Long.parseLong(id));
    }

    @SchemaMapping
    public Instructor instructor(Lesson lesson) {
        return instructorService.findById(lesson.getInstructorId());
    }

    @SchemaMapping
    public List<Review> reviews(Lesson lesson, @Argument Integer first) {
        return reviewService.findByLessonId(lesson.getId(), first);
    }
}