MonkeyCode 教程系列

实战RESTful API开发

MC-023 · 实战篇第5期 · 约1700字 · 实操 25 分钟

官网链接注册更放心哦https://monkeycode-ai.com/?ic=019e0aed-c823-783c-b08a-4f030f891e4e

本期目录

1. 开篇：不只是做页面

2. RESTful API 是什么

3. 需求分析（SDD）

4. 开始开发

5. API 开发的最佳实践

6. 部署上线

7. 漫画解读：码仔的 API 开发

8. 总结与下期预告

开篇：不只是做页面

前面的实战项目有一个共同点：它们都是完整的 Web 应用或自动化工具。

今天换一个方向——开发 API 接口本身。

API 是程序之间通信的桥梁——前端调后端 API 获取数据，日报系统调第三方 API 采集数据。MC-023 以 API 为核心来设计项目——用 AI 快速搭建一个规范、可测试、可扩展的 RESTful API 服务。

RESTful API 是什么

REST（Representational State Transfer）是一种 API 设计风格，核心思想是用 HTTP 方法表达操作意图，用 URL 表达资源。

HTTP 方法	含义	示例
GET	查询资源	GET /api/todos
POST	创建资源	POST /api/todos
PUT	更新资源（全量）	PUT /api/todos/1
PATCH	更新资源（部分）	PATCH /api/todos/1/done
DELETE	删除资源	DELETE /api/todos/1

记住一句话：URL 是名词（资源），HTTP 方法是动词（操作）。

需求分析（SDD）

原始需求：一个待办事项管理 RESTful API，支持完整的 CRUD 操作、数据验证、分页查询、错误处理，并提供 API 文档。

技术栈：Node.js + Express + SQLite + Joi 数据验证

GET    /api/todos          → 获取待办列表（分页、排序、筛选） GET    /api/todos/:id      → 获取单个待办详情 POST   /api/todos          → 创建待办 PUT    /api/todos/:id      → 更新待办（全量） DELETE /api/todos/:id      → 删除待办 PATCH  /api/todos/:id/done → 标记完成/未完成

开始开发

第一步：创建项目

把完整的 API 需求交给 MonkeyCode，包含所有端点、请求/响应格式、数据验证规则、错误处理规范。

第二步：用 curl 测试每个 API

# 获取列表 curl http://localhost:3000/api/todos # 创建待办 curl -X POST http://localhost:3000/api/todos \  -H "Content-Type: application/json" \  -d '{"title":"学习RESTful API","priority":"high"}' # 获取详情 curl http://localhost:3000/api/todos/1 # 更新待办 curl -X PUT http://localhost:3000/api/todos/1 \  -H "Content-Type: application/json" \  -d '{"title":"更新后的标题","priority":"high"}' # 标记完成 curl -X PATCH http://localhost:3000/api/todos/1/done # 删除待办 curl -X DELETE http://localhost:3000/api/todos/1 # 测试分页 curl "http://localhost:3000/api/todos?page=1&limit=2&status=active" # 测试错误处理 curl http://localhost:3000/api/todos/9999      → 404 curl -X POST http://localhost:3000/api/todos \  -H "Content-Type: application/json" -d '{}'  → 400

第三步：验证关键细节

检查项	关注点
HTTP 状态码	201 创建、204 删除、400 验证失败、404 不存在
分页边界	page 超出范围时返回空数组而非报错
数据验证	title 为空、超长、XSS 注入等
错误格式	所有错误都遵循统一格式

API 开发的最佳实践

统一响应格式

// 成功 { "data": {...}, "meta": { "page": 1, "total": 100 } } // 失败 { "error": "VALIDATION_ERROR", "message": "标题不能为空",  "details": [{"field": "title", "rule": "required"}] }

版本管理

URL 中加版本号可以避免破坏已有客户端：

/api/v1/todos  ← 当前版本 /api/v2/todos  ← 未来版本（新增字段、改逻辑）

部署上线

一句话部署，确保所有端点可通过公网访问，添加 CORS 支持以便前端调用。

漫画时间

码仔带你理解 RESTful API 开发

封面：RESTful API 开发

PAGE 01 · SDD需求分析

PAGE 02 · 项目创建与开发

PAGE 03 · curl测试API

PAGE 04 · 错误处理与边界验证

PAGE 05 · 部署上线

PAGE 06 · 总结回顾

总结与下期预告

• RESTful 风格

  URL 表达资源（名词），HTTP 方法表达操作（动词）

• 核心端点

  GET 查询 / POST 创建 / PUT 更新 / DELETE 删除 / PATCH 部分更新

• 数据验证

  必填校验、长度限制、类型检查，返回明确的 400 错误

• 统一格式

  成功和失败都有标准的响应结构

• 测试方法

  curl 命令逐一测试，覆盖正常流程和边界情况

下一期 MC-024：浏览器插件开发——做一个可以装在 Chrome 里的实用工具。

作者：不爱土豆唯爱马铃薯

官网 · 开源 · 文档