API 设计复习：认证、校验、RESTful 与 GraphQL

API 设计不仅是把数据返回给前端，还包括认证、校验、错误处理、状态码和接口风格。

常见认证方式

Basic Authentication 使用用户名和密码，简单但需要 HTTPS。

Token-Based Authentication 通常使用 JWT。

Authorization: Bearer <token>

OAuth 2.0 适合第三方授权登录，例如 Google、GitHub 登录。

API Key 常用于服务到服务调用。

校验

接口输入必须校验。TypeScript 生态中常见选择是 Zod。

const UserSchema = z.object({
  name: z.string(),
  age: z.number().min(0),
});

校验可以防止脏数据进入业务逻辑。

RESTful API

REST 的核心是资源。

GET /api/users
GET /api/users/1
POST /api/users
PUT /api/users/1
DELETE /api/users/1

常见状态码：

• 200 成功
• 201 创建成功
• 400 请求参数错误
• 401 未认证
• 403 无权限
• 404 不存在
• 500 服务端错误

GraphQL

GraphQL 让客户端声明自己需要什么数据。

核心概念：

• Schema：类型定义
• Query：查询
• Mutation：修改
• Subscription：实时订阅
• Resolver：字段解析函数

query {
  user(id: "1") {
    id
    name
  }
}

REST 简单直接，GraphQL 灵活但复杂度更高。选择时要看团队和业务需求。