以前写博客，总想在页面里放一块“每日一句话”，翻遍了各家公共 API，要么要注册，要么限制调用次数，要么返回的内容跟自己的站点气质完全不搭，后来干脆决定自己动手，搭一个真正属于自己的 API 服务。老实说，我不是那种能把框架细节全部背下来的开发者，所以这次直接把 AI 当成了核心工具——不会的问它，写一半让它接着补，报错丢给它解释，再不行就让它在原基础上重写。这个选择帮了我大忙。从初始化项目的第一条命令开始，到服务真正跑在公网上，前前后后只花了一个周末的零碎时间。这篇文章就把当时完整的过程整理出来：需求怎么拆、提示词怎么给、哪些代码是 AI 生成的、哪些是我手工改的、上线后又踩了什么坑。如果你也想用 AI 从零搭自己的 API，这篇可以直接照着走。
1. 这个项目到底要做什么：需求拆解和 AI 的角色边界
1.1 为什么不愿意再用现成公共 API
很多人第一反应是“找个现成接口不就行了”，我在决定自建之前也是这么想的。但实际操作下来，现成公共 API 通常有三个麻烦：一是认证体系复杂，有的要申请 AppKey，有的要 OAuth 跳转，为了在博客侧栏显示一句话，搞这么重完全没有必要；二是调用次数和并发限制，热门接口免费额度低，流量稍微大一点就 429，而且数据内容、返回结构都是别人定义的，想改字段名都没办法；三是服务不稳定，我之前遇到过接口突然下线的，代码还得跟着改。
自建 API 的好处在于数据完全在自己手里，数据结构、错误码、调用频率都可以自定义，想扩展就扩展，而且整个链路从数据库到路由到部署都走一遍之后，后面再做别的项目心里会非常有底。
1.2 把“一个 API 服务”拆成最小可用版本
刚开始做项目最容易犯的错是把需求想得太大。我只给自己定了四个接口，能跑通就算第一版成功：
| 接口 | 动作 | 作用 |
|---|---|---|
/api/quotes/random | GET | 随机返回一条句子，支持按分类筛选 |
/api/quotes | POST | 新增一条句子 |
/api/quotes | GET | 按分类分页查询句子列表 |
/api/health | GET | 健康检查，方便部署后确认服务存活 |
这个 MVP 范围刻意排除了用户系统、登录鉴权、前端页面、复杂缓存。原因很简单：范围越大，AI 生成的代码越不可控，出问题的时候你连错误出在哪一层都定位不了。先做一个完整闭环，后续再迭代，这是我自己做小项目最重要的原则。
1.3 AI 能替我写什么，不能替我决定什么
用好 AI 的前提是搞清楚它的能力边界。对话式大模型本质上是根据你给的上下文，一句一句预测最可能的后续内容，所以它特别擅长的是模式化很强的代码：FastAPI 的路由写法、Pydantic 模型定义、SQLite 的增删改查、pytest 的基础用例，这些几乎全网都有类似样本，它写出来基本靠谱。
但它不擅长替你拍板需求。比如“数据表里到底要存哪些字段”“错误码怎么定义”“要不要做鉴权”“接口返回结构是什么”，这些是需要结合业务场景判断的决策，AI 只会给你一个平均水平的答案，如果你不问它就默认跳过。所以我的用法是：AI 负责把代码从 0 写到 80 分，我来负责确认这 80 分的方向对不对，再把细节补到 95 分。
1.4 开工前的另一个准备工作：让 AI 工具本身先跑通
这个坑很多人会忽略。我用 AI 编程助手的时候，第一次调用就报错，提示类似no api key for provider route，意思是工具默认的模型服务没配好 API Key，整条请求直接失败。后来检查发现是环境变量漏配了。所以开工前先把 AI 工具的认证配好，用一句最简单的“你好”试通，再开始干正事，否则你写再多提示词都是白搭。
2. 技术选型：为什么最后是 FastAPI + SQLite + Uvicorn
2.1 框架对比：让 AI 给我各写一个 hello，再决定
这个项目的核心语言我一开始就定了 Python，因为想做 AI 相关扩展的话 Python 生态最顺手。但框架在 Flask 和 FastAPI 之间犹豫了一下，最后选择 FastAPI，有三个原因：
- 类型校验省心。FastAPI 配合 Pydantic，请求参数和返回结构都能自动校验，前端传错类型直接返回带原因的 422，不用自己在代码里写一堆 if。
- 自带交互式文档。启动之后访问
/docs就是 Swagger 页面，所有接口可以直接在页面上测试，前后端联调的时候特别方便。 - 异步支持。虽然这个项目用不太上，但后面要接大模型 API、做流式返回时，异步就是刚需了。
我不太建议凭感觉选框架。当时我分别让 AI 用 Flask 和 FastAPI 写了同一个“接收一条 JSON 并返回”的接口，对比之后才发现 FastAPI 的请求体验明显更顺，因为 Flask 需要自己解析request.get_json()，而 FastAPI 直接在函数参数里就能拿到校验后的对象。这种对比花不了十分钟，但能帮你省掉后面几小时的返工。
| 关注点 | Flask | FastAPI |
|---|---|---|
| 请求参数校验 | 手动写，容易漏 | Pydantic 自动校验 |
| 接口文档 | 需另装 flasgger | 自动生成/docs |
| 异步支持 | 一般 | 原生支持 |
| 适合规模 | 小工具、模板页 | API 服务、前后端分离项目 |
2.2 数据库：先 SQLite，别急着上 MySQL 或 Redis
数据量级取决于这个 API 面向多少人用。一个个人博客的每日一句话接口，一天可能几百次访问，根本不需要上 MySQL。SQLite 单文件存储、零配置、Python 内置支持，直接把数据库文件放到项目目录里就是全部运维。
我知道很多人会有一种“生产环境必须上正经数据库”的执念，但技术选型永远要匹配场景。SQLite 的瓶颈出现在高并发写入和多实例部署时，个人项目短期内碰不到。真到了需要切换的时候，把数据导出再换 PostgreSQL 也不难。先跑起来，比一步到位更重要。
2.3 本地环境：虚拟环境和启动命令
环境准备其实只有三条命令，但每一步都不要跳：
mkdir quotes-api && cd quotes-api python3 -m venv venv source venv/bin/activate pip install fastapi "uvicorn[standard]" pytest我特意没有用pip install sqlalchemy，因为这种体量的项目直接用标准库sqlite3就够，少一个 ORM 就少一层 AI 瞎编的空间。启动开发服务器也很简单：
uvicorn main:app --reload --port 8000加上--reload，改代码后服务会自动重启。启动后浏览器打开http://127.0.0.1:8000/docs，能看到接口文档，说明骨架已经通了。
2.4 选什么样的 AI 工具来做这个事
我同时用了对话式大模型和 IDE 里的 AI 补全插件。补全插件适合在写代码时即时联想，比如敲了def get_random_quote之后它自动补函数体；对话式模型适合做整体设计、解释报错和写测试用例。
选择时可以关注两点：一是各家大模型 API 的免费额度和上下文长度，小项目用免费额度完全够了；二是注意上下文长度限制，我不会一次性把整个项目代码都丢进去让 AI 优化，很容易触发类似maximum context length的报错，把问题拆细、按文件提问会更稳。
3. 实战搭建：把需求翻译成代码的关键过程
3.1 第一版提示词，我是这么写的
同样让 AI 写代码，不同的人写出来的质量差距可以非常大，差距就在提示词。我给 AI 的提示词不是一句“帮我写个 API”，而是一段结构化的需求说明：
你现在是一个 Python 后端工程师。请帮我创建一个 FastAPI 项目，命名为 quotes-api。 需求： 1. 使用 SQLite 存储句子，字段包括 id、content、category、created_at。 2. 提供四个接口： - GET /api/quotes/random 随机返回一句，支持可选参数 category 筛选； - POST /api/quotes 新增句子，content 必填，category 可选，默认 default； - GET /api/quotes 分页查询，page 和 page_size 参数，支持 category 筛选； - GET /api/health 返回服务状态。 3. 所有接口返回统一结构：{"code": 0, "message": "ok", "data": ...}。 4. 请求参数要校验，content 长度不超过 500，category 不超过 50。 5. 使用标准库 sqlite3，不要引入 SQLAlchemy。注意我加了第 5 条，明确告诉它不要用什么。这一步非常重要，因为 AI 默认倾向选择流行方案，如果你不限制，它就会给你铺一个 SQLAlchemy 的摊子，而对这个项目来说完全不必要。提示词里写得越明确，AI 生成的代码就越贴近你的需求。
3.2 拿到骨架之后，先别急着运行
AI 给的第一版代码通常是一个目录结构，大概长这样：
quotes-api/ ├── main.py # 主程序和路由 ├── database.py # 数据库连接和初始化 ├── requirements.txt # 依赖列表 └── test_quotes.py # 测试用例我拿到之后做的第一件事不是直接运行，而是逐文件读一遍。原因很简单：AI 生成的代码可能存在它“以为存在”的方法，直接运行只会看到一个接一个的报错，还不如先确认结构。尤其是requirements.txt，AI 给出的依赖往往是网上教程里的老版本，我会在安装完后立刻执行一次pip freeze > requirements.txt，把实际版本固化下来，避免过两天完全想不起来环境里装的什么。
3.3 核心代码长什么样：数据库与路由
经过我手动修改后的database.py长这样，核心是开启 WAL 模式，这个后面讲并发坑的时候会再说：
import sqlite3 DATABASE = "quotes.db" def get_db(): conn = sqlite3.connect(DATABASE) conn.row_factory = sqlite3.Row conn.execute("PRAGMA journal_mode=WAL;") conn.execute("PRAGMA busy_timeout=3000;") return conn def init_db(): with get_db() as db: db.execute(""" CREATE TABLE IF NOT EXISTS quotes ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, category TEXT DEFAULT 'default', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) """) db.execute( "CREATE INDEX IF NOT EXISTS idx_quotes_category ON quotes(category)" )main.py里的核心逻辑同样不复杂，但这部分是 AI 生成后我手动改过最多的：
import random from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field from database import get_db, init_db app = FastAPI(title="Quotes API", version="0.1.0") class QuoteIn(BaseModel): content: str = Field(..., min_length=1, max_length=500) category: str = Field("default", max_length=50) @app.on_event("startup") def on_startup(): init_db() @app.get("/api/health") def health(): return {"code": 0, "message": "ok", "data": {"status": "up"}} @app.get("/api/quotes/random") def random_quote(category: str | None = None): db = get_db() if category: row = db.execute( "SELECT * FROM quotes WHERE category=? ORDER BY RANDOM() LIMIT 1", (category,), ).fetchone() else: row = db.execute( "SELECT * FROM quotes ORDER BY RANDOM() LIMIT 1" ).fetchone() if row is None: raise HTTPException(status_code=404, detail="No quote found") return {"code": 0, "message": "ok", "data": dict(row)} @app.post("/api/quotes") def create_quote(quote: QuoteIn): db = get_db() cur = db.execute( "INSERT INTO quotes (content, category) VALUES (?, ?)", (quote.content, quote.category), ) db.commit() return {"code": 0, "message": "ok", "data": {"id": cur.lastrowid}} @app.get("/api/quotes") def list_quotes(category: str | None = None, page: int = 1, page_size: int = 10): db = get_db() where = "WHERE category=?" if category else "" params = (category,) if category else () total = db.execute( f"SELECT COUNT(*) FROM quotes {where}", params ).fetchone()[0] rows = db.execute( f"SELECT * FROM quotes {where} ORDER BY id DESC LIMIT ? OFFSET ?", params + (page_size, (page - 1) * page_size), ).fetchall() return { "code": 0, "message": "ok", "data": {"items": [dict(row) for row in rows], "total": total}, }我不建议让 AI 一次生成一个几百行的单文件把所有逻辑塞进去，因为它很容易漏掉错误处理，而且出现问题后定位困难。拆成database.py和main.py，后续还能继续加auth.py、middleware.py，可维护性会好很多。
3.4 用 pytest 挡住回归，再用 curl 做冒烟验证
代码写完先别急着部署，至少让 AI 写一份基础测试。我会直接丢给它一段话：“根据 main.py 生成 pytest 测试，覆盖空表、新增成功、按分类筛选、分页边界、content 超长时返回 422。”
AI 生成的测试代码大致能覆盖这些场景，但我自己会手动补两个最容易被 AI 忽略的 case：一是空表时随机接口应该返回 404，二是类别不存在时列表接口应该返回空列表而不是报 500。
curl -X POST http://127.0.0.1:8000/api/quotes \ -H "Content-Type: application/json" \ -d '{"content": "学而时习之，不亦说乎", "category": "论语"}' curl http://127.0.0.1:8000/api/quotes/random跑完这几条 curl，整个项目的核心闭环就算通了。这也是我后面所有迭代都依赖的基线：改动任何代码，先跑 pytest，再跑 curl。
4. AI 代码不是拿来就能跑：我实测里遇到的几个真坑
4.1 Content-Type 没配对，接口直接 422
第一个坑发生在刚写完 POST 接口的时候。我用/docs页面测一切正常，但换到 curl 就返回 422 Unprocessable Entity。排查过程是这样的：先看 FastAPI 返回的校验错误信息，提示 content 字段缺失；再用curl -v检查实际发送的请求头，发现我原以为的 JSON 发送，其实Content-Type默认是application/x-www-form-urlencoded，Pydantic 根本没把请求体解析成 JSON。
修复很简单，在 curl 里加一个 Header：
curl -X POST http://127.0.0.1:8000/api/quotes \ -H "Content-Type: application/json" \ -d '{"content": "三人行必有我师", "category": "论语"}'这个坑本身不算难，但它提醒我：AI 生成的代码默认是正确的，真正出错的往往是调用端没有遵循接口约定。以后凡是遇到 422，先检查请求头，再检查参数名，不要一上来就怀疑服务端代码。
4.2 SQLite 并发写：database is locked
第二个坑是上线后才暴露的。一次压测里连续发了多个 POST 请求，服务直接报sqlite3.OperationalError: database is locked。
原因很简单：SQLite 默认在同一时刻只允许一个连接写数据库，多个写入请求同时到达时，后到的会拿不到写锁。AI 生成的代码没有考虑到并发场景，因为它只写了最基础的connect和commit。
解决办法是在连接时开启 WAL 模式和忙碌超时，这两行就是我上面database.py里加的那两个PRAGMA。用生活化的方式理解：WAL 模式相当于让所有人都先在便利贴上写字，再统一整理进笔记本，而不是每个人拿同一支笔抢着写；busy_timeout则是告诉后来的人“等一下，前面的人马上写完”。这两个设置对个人项目的并发量完全够用。
4.3 AI 会一本正经地编造不存在的方法
这是我觉得最值得警惕的坑。有一次让 AI 生成一个 ORM 版本的数据更新逻辑，它给出了一个db.quote_record.update_to_db()之类的方法，运行之后直接AttributeError。问题是 AI 在生成这段代码时完全不加犹豫，看起来就像真有一个官方方法存在一样，初学者很容易被这种自信误导。
我的应对方法是：凡是 AI 代码里出现我不认识的方法或属性，先让它解释“这个方法是哪个库提供的，官方文档在哪”，再让它给出一个不依赖该方法的等价写法。多问两次你会发现，有些方法真的是查无此物，有些是在旧版本里存在但已经废弃了。想避免这类问题，一个可靠的兜底就是跑 pytest，能过测试且业务逻辑正确，就说明这个方法至少在当前环境下是可用的。
4.4 不设输入限制，上线几小时就被人刷写
第四个坑比较疼。我把 POST 接口部署到公网后，几个小时内数据库里多了一堆乱码和广告内容。原因就是我最初图省事，没加访问频率控制，任何人都可以不限次数地往库里写数据。
后来加了两层防护：应用层给每个新增接口做了基于 IP 的简单限流，比如每个 IP 每分钟最多写 5 次；同时把 content 字段的长度校验明确写在 Pydantic 模型里。再后来干脆不在公网开放 POST 接口了，只有带管理 token 的请求才能写入，查询接口保持公开即可。这个经验教训是：只要接口暴露在公网，就会被机器人扫描，输入校验和限流不是可选项，是必选项。
4.5 AI 工具自己也会出问题：API Key 没配、上下文超限
AI 工具本身也不是始终可靠的。我在项目中途想让 AI 对整个 main.py 做一次重构，结果直接返回了上下文超长的报错，提示类似maximum context length。这是因为我把整个项目文件都粘贴进去了，超出了模型单次能处理的最大 token 数。解决方式很简单：按文件拆分提问，或者先让 AI 总结当前代码结构，再针对模块逐段优化。
同样常见的是 API Key 问题，如果 AI 编程工具依赖的模型服务没有正确配置密钥，就会像我开头说的那样，所有对话请求直接失败。所以用 AI 辅助开发时，别只盯着写代码，得先把工具本身的认证、配额、报错信息看明白。
4.6 靠测试兜底：让 AI 生成 pytest，但别盲信
说了这么多坑，最重要的兜底其实只有一个：测试。每让 AI 改完一版代码，我都会执行一遍pytest -q，如果测试挂了，就把失败日志原封不动丢给 AI，让它解释并修复。这会形成一个很高效的循环：
pytest -q测试用例跑得越全，AI 后面越不敢乱来。我实测下来，只要测试里覆盖了边界情况、非法输入和空数据场景，AI 生成的代码整体稳定性会提升一大截。不要嫌写测试麻烦，它是你唯一能低成本确认 AI 代码没在骗你的手段。
5. 从本机到公网：部署上线与基础防护
5.1 用 systemd 把服务托管起来
开发环境用uvicorn main:app --reload没问题，但生产环境不能这样跑，因为终端一关服务就没了。我用 systemd 写了一个服务单元，让 API 作为系统服务常驻运行：
[Unit] Description=Quotes API After=network.target [Service] User=www-data WorkingDirectory=/srv/quotes-api ExecStart=/srv/quotes-api/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 Restart=always [Install] WantedBy=multi-user.target注意这里--host 127.0.0.1，意思是服务只在本机监听，不直接暴露到公网，后面由 Nginx 统一接收外部流量。保存后执行systemctl enable --now quotes-api，服务会在开机时自启，并且进程崩溃后自动重启。
5.2 Nginx 反向代理 + HTTPS
用 Nginx 的好处是能统一处理 HTTPS、限流、请求头和安全策略。我的 Nginx 配置很简单：
server { listen 80; server_name api.example.com; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }HTTPS 直接用 certbot 申请免费证书，一条命令就能把证书和自动续期都配置好：
certbot --nginx -d api.example.com这里不用自己手动折腾证书文件，certbot 会修改 Nginx 配置并把 HTTP 流量重定向到 HTTPS。上线后我用curl https://api.example.com/api/health验证了一次，确认公网入口完全正常。
5.3 至少要做这层防护：限流、身份识别、日志
给公网 API 做防护，我按优先级做了三件事：
- Nginx 层限流：对
/api/路径做了每秒 10 次的整体限流，超出直接返回 503。这能挡住大部分粗暴刷接口的机器人。 - 写接口加 Token：POST 接口现在必须带
Authorization: Bearer <TOKEN>才能调用，查询接口保持公开。Token 通过环境变量注入，不写进代码库。 - 日志输出到标准输出：不把日志写进文件，直接用 systemd 的 journal 收集，这样所有日志都在
journalctl里，排查问题时不用登录服务器去翻文件。
5.4 上线后第一件事：看日志而不是看页面
上线后的第一次检查，我会先看日志，而不是先调接口。因为接口只验证“服务活着”，日志才能告诉你“服务有没有在被乱搞”。
journalctl -u quotes-api -f我第一次上线后的日志里全是 404 扫描记录，各种随机路径的探测请求，说明服务一暴露到公网就会被扫描器盯上。这也是为什么我坚持不在公网开放写接口、必须加限流的原因。日志里如果看到某个 IP 频繁访问，直接在 Nginx 层把它禁掉即可，不用改动应用代码。
6. 如果再让我重做一遍，我会提前改掉的三件事
6.1 先定统一错误码和返回结构，再开始写路由
这个项目第一版接口返回结构是完全一致的，但错误返回却被我写得比较随意：有的接口直接返回 HTTP 422 的 FastAPI 默认结构，有的返回 404{"detail":"..."}，前端对接时要针对不同接口写两套解析逻辑。后面我统一把返回格式固定为{"code": 0, "message": "ok", "data": ...}，业务错误也用同一个结构返回。这个教训是：返回结构属于接口契约，写代码之前就应该定好，而不是写完再补。
6.2 数据库结构从第一天就交给迁移工具
一开始我在init_db()里用CREATE TABLE IF NOT EXISTS建表，这种方式对单表项目足够，但一旦你想加字段、加索引，就会面临“线上库已经建好、测试库还是新结构”的混乱。后来我引入了 Alembic 做数据库迁移，每改一次表结构都会生成一个迁移文件，团队成员在不同环境下执行同一套迁移，数据库结构就不会跑偏。对于个人项目可能不算必须，但我建议一旦表结构要变动第二次，就值得上一套迁移工具了。
6.3 配置和密钥集中管理，别写死在代码里
上线之后改配置会非常痛苦。最初我把数据库路径、Token、允许的跨域来源都直接写在了main.py里，后来要改其中一个，就得重新部署一次。正确的做法是用环境变量或.env文件统一管理：
from pydantic_settings import BaseSettings class Settings(BaseSettings): api_token: str database_path: str = "quotes.db" cors_origins: list[str] = ["*"] class Config: env_file = ".env" settings = Settings()这个改动带来的直接好处是：改 Token、切数据库路径都只需要改环境变量，不用碰代码；而且密钥不会因为代码被复制而泄露。如果你也在用 AI 辅助开发，有一点需要特别留意：AI 默认生成代码时不会主动考虑密钥管理，它会很自然地把密钥作为常量写进代码里，这正是需要你人工把关的地方。
最后再分享一个我个人的固定习惯：每次让 AI 生成完代码，我不会立刻信任它，而是先看一眼依赖和函数名，再跑一遍 pytest，最后用 curl 打几个“脏数据”——超长字符串、空字符串、不存在的 ID，哪个打崩了就让 AI 解释原因。这套流程帮我挡掉了绝大多数上线后才会发现的坑。这个项目做完之后，我又用同样的方法搭过两个内部小工具，流程基本固定为三步：拆需求、把需求变成提示词、用测试验收 AI 的输出。如果你也想试着用 AI 从零搭自己的 API，建议从今天这个小项目开始，把它当成你带的第一个实习生来用。测试通过的那一刻，你会比直接让它给你一个“完整项目”更有成就感。
