手帐 Blog

主题

10 · 迷你 HTTP API 小项目落地 ​

目标：两周内交付一个可运行、有测试的迷你笔记 API——对齐暑假计划小项目选项 2。
前置：本系列 02～09；官方 net/http · testing

1. 范围（刻意做小） ​

做 ​

方法路径行为
GET/health200 + ok
GET/notes返回内存中全部笔记 JSON 数组
POST/notesbody: {"content":"..."}，返回含 id 的笔记
GET/notes/{id}找到 200；找不到 404 JSON 错误

不做（本版禁止） ​

  • 数据库、Redis、JWT、Swagger UI
  • Gin / Echo / Fiber
  • 把 Journal 整后端搬过来

验收（打勾即暑假 Go 线「期望」达标） ​

  • [ ] go test ./... 通过（含至少 1 个 Handler 测试）
  • [ ] go run . 后可用 curl/Apifox 走通上表
  • [ ] README 十行内说明如何运行
  • [ ] 能向别人讲清：路由、JSON、错误、测试各在哪

2. 建议目录 ​

text
notesapi/
  go.mod
  main.go          # 组装 mux，ListenAndServe
  note.go          # Note 类型与内存 Store
  note_test.go     # Store 的 table-driven 测试
  handler.go       # HTTP handlers
  handler_test.go  # httptest 测试
  README.md

go mod init 名自定，例如 example.com/notesapi。

3. 设计要点（串起前几篇） ​

主题落点
接口Storer 接口 + MemoryStore（05）
错误Handler 里转成 HTTP 状态码；Store 返回 error（04）
JSON请求解码 / 响应编码（07）
context预留：r.Context() 传入 Store（即便内存版暂不用）（06）
测试Store 单测 + Handler httptest（08）
AI用 09 的清单审每一轮生成

4. 里程碑（周末友好） ​

日交付
Day 1module + Note + MemoryStore + 单测绿灯
Day 2POST/GET /notes + curl 通
Day 3GET /notes/{id} + 统一错误 JSON
Day 4httptest 测试；go vet；补 README
Day 5（可选）日志中间件；优雅一点的 http.Server + 超时

路径参数：Go 1.22+ 见 net/http 文档中的 pattern；低版本用前缀解析或 Split。

5. 错误响应约定（简单即可） ​

json
{"error":"not found"}
情况状态码
JSON 无法解析400
缺少 content400
id 不存在404
方法不允许405
未处理恐慌（应避免）别靠 panic；要 recover 也留到以后

6. 推荐自测命令 ​

bash
go test ./...
go vet ./...
go run .

curl -s http://127.0.0.1:8080/health
curl -s -X POST http://127.0.0.1:8080/notes -H "Content-Type: application/json" -d "{\"content\":\"hello\"}"
curl -s http://127.0.0.1:8080/notes

7. 和 AI 协作的推荐节奏 ​

  1. 你写好 Storer 接口与测试表（红灯）。
  2. AI 实现 MemoryStore 到绿灯。
  3. 你写 Handler 测试表。
  4. AI 实现 Handler。
  5. 用 09 审查清单 过一遍。
  6. 自己读完 git diff 再宣告完成。

提示词开头固定贴上：

text
只使用标准库。项目是内存笔记 API。不要添加路由框架。
先让测试通过，再谈重构。

8. 做完之后 ​

  • 更新暑假计划「实际进度」里 Go 一栏。
  • 可按 blog 后续规划 另写「Go 小项目复盘」（目录、踩坑、是否下一步上框架）。
  • 下一阶段：按 11 · 全栈中间件路线图 进入 Gin 生产栈 → Redis → Docker（勿一上来并行 gRPC/K8s）。

9. 阶段一收束 ​

你若按 01→10 走完，应具备：

  1. 官方文档导航能力
  2. modules + 标准库 HTTP/JSON
  3. 基础并发与 context
  4. table-driven 测试
  5. AI 辅助但不失控的工作流

阶段二从 11 · 路线图 开始；先把测试与错误处理讲漂亮，再上框架与中间件。

官方入口 ​