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 灵活但复杂度更高。选择时要看团队和业务需求。

延伸理解

复习这篇时，不要只记住名词，要把重点放在 认证、鉴权、输入校验、REST 资源建模、GraphQL 查询边界和错误语义。这类知识如果只停留在定义层面，很容易在面试或项目中答得很散。更好的理解方式是把它放进一个具体场景：谁在调用它，输入从哪里来，失败后谁负责恢复，数据或状态会不会被重复处理。

后端设计的重点不是把接口跑通，而是让认证、校验、错误处理、幂等性、日志和版本演进都有明确位置。
接口字段要服务于业务语义，不能只是数据库表结构的直接暴露。
评审一个 API 时，至少检查正常路径、权限失败、输入非法、资源不存在和外部依赖失败。

在真实项目中，可以把它当成一个判断框架：先确认输入、约束、失败场景和可观测性，再决定具体工具或写法。如果一个方案看起来很简单，要继续追问它在规模扩大、权限变化、异常恢复和团队协作下是否仍然成立。

实践检查清单

明确这个知识点在系统中的位置：是开发时约束、运行时能力、基础设施能力，还是协作流程。
写出一个最小可运行例子，并补一个失败例子；只会写 happy path 说明理解还不够稳。
记录常见误用：例如边界条件、权限假设、性能假设、同步/异步差异或环境差异。
把概念和项目经历关联起来：如果面试被追问，可以用自己的项目说明为什么这样选。
最后用一句话总结取舍：它牺牲了什么，换来了什么。

自测问题

这个主题解决的核心问题是什么？
如果不用当前方案，还有哪些替代方案？代价是什么？
最容易出错的边界条件在哪里？
如何在代码、测试或监控中验证它真的可靠？

项目化应用场景

可以把这类知识放到一个用户系统或内容管理系统里理解：前端提交表单，后端先做认证，再做权限检查和输入校验，然后执行业务逻辑，最后返回稳定的状态码和错误结构。一个成熟后端接口不应该只考虑成功返回数据，还要考虑 token 过期、用户无权限、重复提交、参数非法、数据库写入失败和外部服务超时。接口文档、日志、监控和测试用例都应该围绕这些路径展开。

常见误区：

把认证和鉴权混为一谈。
只在前端校验输入，后端直接相信请求。
所有错误都返回 500，导致调用方无法恢复。

目录