项目二 Workers 与 D1 笔记 API

用迁移、参数化 SQL、结构化错误和本地 D1 完成一个可审查的 CRUD API。

PROJECT 02进阶约 55 分钟产出：Notes CRUD API

完成标准

本地 migration 成功；写操作需要 Secret；列表、创建、读取、删除、校验失败和数据库失败都有稳定结果；所有用户值通过 prepare().bind() 进入 SQL。

架构与文件

HTTP Request → Worker validation/router → D1 prepared statement → JSON response

README.md

wrangler.jsonc

0001_create_notes.sql

index.mjs

源码位于 examples/workers-d1-api/。它用 WRITE_KEY 保护 POST/DELETE，限制 body 大小、标题长度与列表条数；返回列显式列出，不使用 SELECT *；内部异常不会回显 SQL。

本地运行

应用 migration

pnpm wrangler d1 migrations apply orange-book-notes --local --config examples/workers-d1-api/wrangler.jsonc

启动 Worker

cp examples/workers-d1-api/.dev.vars.example examples/workers-d1-api/.dev.vars
pnpm wrangler dev --config examples/workers-d1-api/wrangler.jsonc

编辑本地 .dev.vars，替换占位值；该文件不能提交。线上 Secret 需在确认目标账号后另行设置。

创建并读取

curl -i http://127.0.0.1:8787/api/notes \
  -H 'content-type: application/json' \
  -H 'x-write-key: <your-local-write-secret>' \
  --data '{"title":"First note","body":"Verified locally"}'
curl -i 'http://127.0.0.1:8787/api/notes?limit=10'

验证错误分支

curl -i 'http://127.0.0.1:8787/api/notes?limit=999'
curl -i -X PATCH http://127.0.0.1:8787/api/notes

预期为 400 invalid_limit 与 405 method_not_allowed。

d1 create、migrations apply --remote、生产 Secret 设置与 deploy 都会修改 Cloudflare 状态，本阶段不自动执行。生产迁移前备份、在预览数据库验证、确认旧代码仍能读新 Schema；回滚代码不能撤销已写入的数据。泄露 WRITE_KEY 时必须轮换。该共享 Key 只用于服务端教学调用，不能写进浏览器代码；公开编辑器需要真实的用户认证和授权。

下一步：Workers AI + Vectorize 知识助手。

项目二 Workers 与 D1 笔记 API

架构与文件

本地运行

应用 migration

启动 Worker

创建并读取

验证错误分支

远程边界与回滚

官方来源

这篇内容帮你完成目标了吗？

本页目录