API 基础

这一课你将能做到

1. 说清楚 API 是什么、解决什么问题，以及它在前后端分离架构中的位置
2. 用 curl 调用本站真实 API（/api/lessons），并解读返回的 JSON 结构
3. 理解资源（Resource）思维：把数据和能力抽象成可寻址的 URI

为什么要学

你写的每一个 Spring Boot Controller，本质上都是在设计 API。前端同事调你的接口、第三方系统对接你的服务、App 拉取数据——全靠 API。设计得好，调用方省心；设计得烂，天天被问「这个字段什么意思」「为什么又报 500」。

面试必问：REST 是什么？GET 和 POST 区别？幂等性怎么保证？这些不是背概念，是你每天都在做的事。

先建立图像

┌─────────┐      HTTP 请求       ┌─────────────┐      SQL        ┌────────┐
│  前端   │  ──────────────────► │  Spring Boot │  ─────────────► │ MySQL  │
│ (React) │  ◄────────────────── │  Controller  │ ◄─────────────  │        │
└─────────┘      JSON 响应       └─────────────┘                 └────────┘

API 就是中间这一层「契约」：前端不需要知道你怎么存数据，只需要知道「GET /api/lessons 能拿到课程列表」。

跟着做

步骤 1：调用本站真实 API

打开终端，执行：

curl -s http://localhost:8080/api/lessons | head -c 500

你会看到类似这样的 JSON：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "Java 基础语法",
      "slug": "java-basic-syntax",
      "trackId": "java-fundamentals"
    }
  ]
}

这就是 API 的「契约」：请求方发 HTTP 请求，服务方返回结构化数据。

步骤 2：写一个最简单的 Controller

@RestController
@RequestMapping("/api/lessons")
public class LessonController {

    private final LessonService lessonService;

    public LessonController(LessonService lessonService) {
        this.lessonService = lessonService;
    }

    @GetMapping
    public ApiResponse<List<Lesson>> list() {
        List<Lesson> lessons = lessonService.findAll();
        return ApiResponse.success(lessons);
    }

    @GetMapping("/{id}")
    public ApiResponse<Lesson> getById(@PathVariable Long id) {
        Lesson lesson = lessonService.findById(id);
        return ApiResponse.success(lesson);
    }
}

@RestController = @Controller + @ResponseBody，表示这个类处理 HTTP 请求并直接返回 JSON，不渲染页面。

步骤 3：理解资源思维

把「课程」看作资源：

操作	HTTP 方法	URI	含义
查询列表	GET	/api/lessons	获取所有课程
查询单个	GET	/api/lessons/1	获取 id=1 的课程
创建	POST	/api/lessons	新增一门课程
全量更新	PUT	/api/lessons/1	替换 id=1 的课程
删除	DELETE	/api/lessons/1	删除 id=1 的课程

URI 里放「名词」（资源），HTTP 方法表达「动作」。这是 REST 的核心思想。

步骤 4：POST 创建资源

curl -X POST http://localhost:8080/api/lessons \
  -H "Content-Type: application/json" \
  -d '{"title":"Spring Boot 入门","slug":"spring-boot-intro","trackId":"java-web"}'

-H 设置请求头，-d 是请求体。服务器解析 JSON，存入数据库，返回创建后的资源。

讲清楚要点

1. API 是契约，不是实现：前端和后端通过 API 约定「传什么、返回什么」，双方可以并行开发。契约一旦发布，改动要谨慎，否则调用方会崩。
2. REST 是一种风格，不是标准：REST（Representational State Transfer）由 Roy Fielding 在 2000 年提出，核心约束是「无状态、可缓存、统一接口、分层系统」。符合这些约束的 API 叫 RESTful。
3. 无状态（Stateless）：每个请求必须包含所有必要信息，服务器不保存会话状态。好处是任意一台服务器都能处理请求，方便水平扩展。
4. 统一接口（Uniform Interface）：用标准 HTTP 方法操作资源，URI 标识资源，自描述消息。这样 API 一看就懂，不需要额外文档也能猜个大概。
5. JSON 是事实标准：XML 太重，JSON 轻量、可读性好、浏览器原生支持。Spring Boot 默认用 Jackson 做序列化/反序列化。

你可能会懵的地方

• API 和 SDK 有什么区别？ API 是接口约定（URI、方法、参数、返回值格式）；SDK 是封装好的工具包（比如 Java SDK、Python SDK），帮你把 HTTP 调用包装成函数调用。SDK 底层还是调 API。

• REST 和 RESTful 是一回事吗？ REST 是理论风格；RESTful 是「符合 REST 风格的」。日常说「写个 REST API」就是「写个 RESTful API」。

• 为什么 URI 里用复数名词？ /api/lessons 表示「课程集合」，/api/lessons/1 表示「集合中的一个元素」。单数 /api/lesson 会让人误以为只操作一个固定资源。

• GET 请求能带 body 吗？ HTTP 规范没禁止，但大多数服务器和客户端不支持。查询参数放 URL 里，复杂条件用 POST + body（但这就不是纯 REST 了）。

• API 和 RPC 有什么区别？ RPC（Remote Procedure Call）是「调用远程函数」，比如 getUserById(1)；REST 是「操作资源」，比如 GET /users/1。RPC 更灵活，REST 更规范。现代微服务常用 gRPC（基于 HTTP/2 的 RPC）。

错法对照

错法	问题	正解
GET /api/getLesson?id=1	URI 里出现动词，违背资源思维	GET /api/lessons/1
所有请求都用 POST	失去 HTTP 方法的语义，缓存、日志、监控都失效	按操作类型选方法
返回 {"data": null, "msg": "ok"}	结构不一致，调用方无法统一处理	统一响应包装 {code, message, data}
把密码放在 URL 参数里	URL 会被记录到日志、浏览器历史	敏感信息放 body 或 header

卡点急救

1. 404 Not Found：检查 URI 拼写、HTTP 方法是否匹配、Controller 是否加了 @RequestMapping。
2. 415 Unsupported Media Type：POST/PUT 请求没加 Content-Type: application/json。
3. CORS 报错：浏览器跨域限制，后端需要配置 @CrossOrigin 或全局 CORS 规则。

面试常问

• REST 的四个核心约束是什么？ 无状态、可缓存、统一接口、分层系统。能展开讲每个约束的含义和好处。

• GET 和 POST 的区别？ GET 幂等、可缓存、参数在 URL、有长度限制；POST 非幂等、不可缓存、参数在 body、无长度限制。GET 用于查询，POST 用于创建/修改。

• 什么是幂等性？为什么重要？ 幂等 = 多次执行结果相同。GET、PUT、DELETE 是幂等的，POST 不是。网络重试、用户双击、消息队列重发时，幂等设计防止重复创建/扣款。

自测三问

1. 用 REST 风格设计一个「提交作业」的 API，URI 和方法怎么写？
2. 为什么说 REST 是无状态的？这个特性带来什么好处？
3. 如果让你设计「批量删除课程」的 API，你会怎么做？

小结一句话

API 是前后端之间的契约；REST 用「资源 + HTTP 方法」让接口自描述、可预测；掌握资源思维是设计好 API 的第一步。

延伸

• Roy Fielding 的 REST 论文
• MDN HTTP 概述
• 下一课：HTTP 协议层——深入请求方法、状态码、Header 与 CORS。