前阵子想给个人项目加一套API服务把数据接口暴露给小程序和前端用。正好这两年AI编程工具越来越能打DeepSeek、智谱、讯飞星火这类大模型API的免费额度也够个人项目折腾我就干脆做了次彻底的实战全程让AI当主力从零把一个API服务搭出来能注册、能写数据、能部署上线还接进了大模型能力。这篇文章是这次实践的完整还原从需求拆解、技术选型、提示词设计、代码生成、调试部署到踩坑记录都有。想用AI快速落地后端服务的人或者好奇AI生成的代码到底能不能直接上线的这篇应该能给你一份能参考的答案。1. 项目整体设计与思路拆解1.1 为什么我会想到用AI来搭API服务先交代下背景。我有一个AI灵感笔记的小想法用户把碎片想法存下来隔段时间让大模型帮忙总结、提炼关键词、甚至扩展成文章大纲。说白了就是一套标准的后端服务要管用户、管笔记数据还要跟大模型API打交道。传统做法里这种项目绕不开一堆重复劳动项目脚手架、数据库配置、CURD接口、鉴权逻辑、部署配置每一样都得查文档、试错没个两三天出不来能跑通的东西。AI在这个过程里扮演的不只是代码生成器更像一个随叫随到的结对编程搭档。我列一下它在我这次项目里实际承担的工作生成项目雏形一个提示词让它输出FastAPI完整骨架包括依赖文件、启动脚本、路由结构省掉了我对着文档翻半天的工夫。批量产出重复代码用户管理、笔记增删改查这类模式固定的接口AI几秒钟就能给出一套能改着用的实现。当人肉文档记不清某个中间件怎么配、某个依赖参数怎么写时直接问AI比翻官方文档快得多。代码审查帮手写完核心逻辑后让AI换一个角度挑毛病往往能发现边界条件没考虑、异常没捕获这类问题。但这不代表AI能包办一切。我这次最大的体会是它擅长的是把话变成代码而什么话该说、怎么说、说的边界在哪仍然得你自己拿主意。业务逻辑的合理性、数据模型的设计、安全边界的划分这些基本功AI替代不了它只是帮你把从想法到初稿的时间压缩到原来的十分之一。1.2 技术选型为什么最终选择了FastAPI MySQL Redis技术选型是一个API服务的起点。我在项目开始前做了个对比把几个主流方案摊开来看框架性能类型校验自动文档异步支持上手难度FastAPI高接近GoPydantic内置自动生成开箱即用原生异步中等Flask中需自己加库需额外配置需额外插件低Express(Node)中高需额外配置需额外配置原生异步中等最终选了FastAPI理由很实在它自带自动交互式文档浏览器打开/docs就能调试每个接口这对AI生成代码后的验证环节太重要了参数校验、响应模型这些和Pydantic深度集成相当于类型安全直接内置性能表现也完全够个人项目用。数据层选了MySQL Redis的组合。MySQL是业务数据的存储核心成熟稳定社区资料多就算AI生成的SQL有问题排查成本也最低Redis主要承担两件事一是给热点接口做缓存二是后面做API限流时存计数器。这里也能看出技术选型的一个原则不追新、不炫技选择自己最熟悉、排错资料最多的那一套AI侧的容错率反而更高。顺便说一句大模型API的选型。这次项目里要接AI总结功能我在DeepSeek、智谱GLM、讯飞星火之间做了对比。它们都提供免费测试额度对个人项目来说足够用调用方式也统一兼容OpenAI的SDK意味着AI生成的调用代码可以在不同厂商间无缝切换。我最终把大模型API的接入抽象成了一层独立服务厂商的api_key和base_url全部走环境变量方便随时切换。这类细节建议你在动手前就想好不然AI生成的代码里到处硬编码后期维护会很痛苦。2. 核心细节解析与实操要点2.1 AI辅助编码的关键提示词设计很多人让AI写代码结果拿回来的东西没法用问题往往不在AI而在提示词。拿帮我写个API这种需求去问AI它能给你一百种天马行空的答案。我这次实践下来发现一个合格的后端提示词至少包含四个维度的信息角色设定、任务描述、约束条件、输出格式。举个实际例子。我在项目开始时给AI的提示词大致是这样你是一位资深的Python后端工程师。请基于FastAPI生成一个API服务的项目骨架要求如下 1. 使用Python 3.10FastAPI 0.100SQLAlchemy 2.0PyMySQL 2. 项目结构分为app/main.py、app/models.py、app/schemas.py、app/routers/ 3. 实现用户注册和登录接口密码使用bcrypt加密存储 4. 实现笔记的增删改查接口接口路径遵循RESTful规范 5. 所有接口的响应统一为{code:0,data:...}格式 6. 请逐个文件输出完整代码并在关键位置添加注释。这个提示词的效果和我之前随手写的帮我搞一个笔记API完全是两个量级。角色限定让AI用后端工程师的标准来写代码任务描述把要做什么说清楚约束条件把依赖版本和实现方式都钉死了输出格式则让结果更可控。这里有几个我踩过的坑新手尤其容易栽进去没锁版本AI默认生成的依赖可能用了它训练数据里最热门的版本但版本号和实际安装到的最新版经常对不上。比如pydantic从v1升到v2后很多写法直接废了。我的做法是让AI每次生成requirements.txt时必须标注测试过的版本组合然后装完后立刻跑一遍测试验证。需求没写边界只说做个删除笔记接口AI给的可能是物理删除但业务上你可能希望逻辑删除。这类业务规则不写进去AI猜不出来的。没让它解释代码AI输出代码后追加一句请解释一下认证依赖函数的执行流程。逼它解释就是在帮你做代码审查很多隐藏的逻辑坑会在这一步暴露出来。2.2 API设计规范与数据库建模动手写代码前先把接口画出来。这里不一定要画正经的API文档哪怕在备忘录里列一个接口清单也够用了。我给这个AI灵感笔记服务设计的核心接口是这样方法路径功能权限POST/api/v1/users/register用户注册公开POST/api/v1/users/login用户登录公开GET/api/v1/notes获取笔记列表需登录POST/api/v1/notes创建笔记需登录GET/api/v1/notes/{id}获取笔记详情需登录PATCH/api/v1/notes/{id}更新笔记需登录DELETE/api/v1/notes/{id}删除笔记需登录POST/api/v1/ai/summarizeAI总结笔记需登录路径规划遵循RESTful直觉资源用名词复数操作由HTTP方法表达版本号直接放进路径前缀/api/v1避免未来接口升级时打挂老客户端。数据库建模这部分我让AI给出第一版设计然后自己做了review。AI生成的初版表结构有个典型问题它给我加了购买会员之类的多余字段差点把方向带偏。我最终定下来的核心就两张表CREATE TABLE users ( id BIGINT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(64) UNIQUE NOT NULL, password_hash VARCHAR(128) NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE notes ( id BIGINT AUTO_INCREMENT PRIMARY KEY, user_id BIGINT NOT NULL, title VARCHAR(200) NOT NULL, content TEXT NOT NULL, summary TEXT, status TINYINT DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_user_id (user_id), CONSTRAINT fk_notes_user FOREIGN KEY (user_id) REFERENCES users(id) );表结构里有个经验值得单独说给notes.user_id加了普通索引就够了个人项目的体量完全不需要搞什么分区表、读写分离。无数人会犯的错误就是脑子里装着大厂架构一上来就堆组件结果运维成本比开发成本还高。我在这个项目里时刻提醒自己能用单表解决的绝不拆表。3. 实操过程与核心环节实现3.1 用AI生成项目骨架并跑通选好方案、理清接口就可以请AI动工了。我用的是DeepSeek的网页对话窗口先按前文的提示词让它输出项目骨架。AI陆续给了几段文件这里我只贴核心的app/main.py你感受下AI生成的代码质量from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.routers import users, notes, ai app FastAPI( titleAI灵感笔记API, description一个结合大模型能力的个人笔记服务, version1.0.0, ) app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], ) app.include_router(users.router, prefix/api/v1, tags[用户]) app.include_router(notes.router, prefix/api/v1, tags[笔记]) app.include_router(ai.router, prefix/api/v1, tags[AI能力]) app.get(/health) def health_check(): return {status: ok}这段代码质量挺高但有一个安全细节需要你警觉allow_origins[*]这种配置如果做带鉴权的API是不可接受的等于是允许任意前端读取任意接口数据。我拿到代码后立刻改了只留了自己小程序的域名。这就是前面说的AI负责产出你负责把关。把文件逐个保存到本地后用一条命令跑起来看效果pip install -r requirements.txt uvicorn app.main:app --reload --port 8000浏览器打开http://127.0.0.1:8000/docs看到Swagger文档页面出现的瞬间项目就算正式活了。这一步的体验对比传统开发太明显了以前光配项目结构、装依赖、处理启动报错就得耗掉一下午现在AI十分钟给了初稿我只是做验证和修正。3.2 数据库接入与数据模型迁移项目骨架跑通后下一步接入数据库。AI生成的SQLAlchemy模型基本能用稍微改改就直接上线了。app/models.py里的核心内容是这样from sqlalchemy import Column, BigInteger, String, Text, DateTime, func from sqlalchemy.orm import declarative_base Base declarative_base() class User(Base): __tablename__ users id Column(BigInteger, primary_keyTrue, autoincrementTrue) username Column(String(64), uniqueTrue, nullableFalse) password_hash Column(String(128), nullableFalse) created_at Column(DateTime, defaultfunc.now()) class Note(Base): __tablename__ notes id Column(BigInteger, primary_keyTrue, autoincrementTrue) user_id Column(BigInteger, nullableFalse) title Column(String(200), nullableFalse) content Column(Text, nullableFalse) summary Column(Text) status Column(BigInteger, default1) created_at Column(DateTime, defaultfunc.now()) updated_at Column(DateTime, defaultfunc.now(), onupdatefunc.now())数据库连接这一块我用的是SQLAlchemy 2.0风格连接串放在环境变量里读取避免把账号密码写进代码。数据库初始化也不需要额外工具启动时执行一次建表就能跑省掉了Migrations的复杂度个人项目完全够用from sqlalchemy.orm import sessionmaker from sqlalchemy import create_engine import os DATABASE_URL os.getenv( DATABASE_URL, mysqlpymysql://root:password127.0.0.1:3306/ai_notes?charsetutf8mb4 ) engine create_engine(DATABASE_URL, pool_size10, pool_recycle3600) SessionLocal sessionmaker(bindengine, autoflushFalse, autocommitFalse)这里有个值得展开的细节charsetutf8mb4。如果漏掉这个参数MySQL的默认字符集会让你存的emoji全部变成问号。AI在第一次给我的连接串里就没加这个参数我是在测试写入一个带表情符号的笔记标题时发现的。这种细节就是典型的AI不知道业务上下文但你知道的地方。3.3 鉴权与API密钥管理一个对外暴露的API服务最不能省的就是身份识别。我在这个项目里选择了API Key方案而不是JWT主要考虑是把服务给我的小程序用API Key的方式更直观、好调试——小程序请求时带一个X-API-Key请求头后端校验通过就放行。登录接口先验证用户名和密码验证通过后签发一个API Key给客户端留存。签发逻辑的AI初稿用的是uuid4().hex生成一段随机字符串并存库这个方案我认可但加了一个安全整改密钥不做明文存储只存它的SHA256哈希值。这样即使数据库被拖走攻击者也拿不到可用的Key。核心代码如下import hashlib import secrets def generate_api_key(): return secrets.token_hex(32) def hash_api_key(api_key: str) - str: return hashlib.sha256(api_key.encode()).hexdigest()校验依赖用FastAPI的Depends机制写了个通用函数所有需要登录的接口直接声明依赖就行from fastapi import Depends, HTTPException, Security from fastapi.security import APIKeyHeader api_key_header APIKeyHeader(nameX-API-Key, auto_errorFalse) def verify_api_key(api_key: str Security(api_key_header)): if not api_key: raise HTTPException(status_code401, detail缺少API Key) digested hash_api_key(api_key) # 到数据库查询 digested 是否存在存在则返回用户信息 ...密码存储用的是bcrypt库AI生成代码时默认用了这个方案我查了下确认是当下最稳妥的选择之一就没改。这里要提醒的是一定不能让AI自己发明一个加密算法——曾经有个AI生成代码里用了自定义的异或运算来加密密码那跟明文没区别。安全相关的功能必须限定AI用业界公认的成熟方案。3.4 容器化部署与域名上线本地能跑只是开始真正常用的API得部署到服务器上才能生效。我买了台2核4G的轻量服务器系统和云服务商没有特别要求你按自己熟悉的来就行。部署方案直接选择Docker Compose把应用和数据库一起编排这样迁移服务器时能整个环境一起搬走。AI在这里帮我生成了两个文件效果比手写快得多。先看DockerfileFROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]再看docker-compose.ymlversion: 3.9 services: api: build: . ports: - 8000:8000 environment: - DATABASE_URLmysqlpymysql://root:passworddb:3306/ai_notes?charsetutf8mb4 - DEEPSEEK_API_KEY${DEEPSEEK_API_KEY} depends_on: - db db: image: mysql:8.0 environment: - MYSQL_ROOT_PASSWORDpassword volumes: - mysql_data:/var/lib/mysql volumes: mysql_data:部署上线时我踩了一个非常典型的坑AI生成的环境变量里数据库地址写的是127.0.0.1这在Docker网络里是不通的因为api容器和db容器不是一个网络空间。连接串必须改成服务名db也就是上面compose文件里DATABASE_URL中写的db:3306。这个坑不止一次出现在AI生成的项目里你如果也是用Docker部署务必检查数据库地址写的是不是容器服务名而不是回环地址。部署命令很简单服务器上安装好Docker后docker compose up -d --build启动成功后再用Nginx做反向代理给服务域名配上HTTPS证书。这些配置我在网上找了模板改了一下完全不需要AI参与。至此一个真正能通过HTTPS访问的API服务就上线了。3.5 接入大模型API让服务学会思考到了这个项目最核心的功能点让笔记服务拥有AI能力。我的需求是提供一个接口客户端传入一篇笔记内容后端调用大模型API返回总结和几个关键词。这个功能在技术层面正好可以验证一件事第三方大模型API的接入到底有多简单。先后装好依赖pip install openai然后写一个独立的大模型客户端模块。这里有个好消息是DeepSeek、智谱、讯飞星火都兼容OpenAI SDK格式所以调用代码可以非常统一from openai import OpenAI import os client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(LLM_BASE_URL, https://api.deepseek.com), ) def summarize(content: str) - str: resp client.chat.completions.create( modelos.getenv(LLM_MODEL, deepseek-chat), messages[ {role: system, content: 你是一名称职的编辑请对用户输入的内容进行总结提炼出不超过5个关键词并以JSON格式返回。}, {role: user, content: content}, ], temperature0.3, ) return resp.choices[0].message.content这段代码里有两个值得留意的点。第一temperature设置成了0.3因为总结场景我们希望输出稳定、可复现温度太高会得到每次都不一样的花式总结。第二system提示词里明确要求返回JSON格式这是让大模型输出结构化数据最省事的做法比自己写正则从自由文本里抠关键词靠谱得多。接口层再包一层AI生成的路由代码稍作修改就能用router.post(/ai/summarize) def summarize_note(payload: NoteSummarizeRequest, user: User Depends(verify_api_key)): summary summarize(payload.content) return {code: 0, data: {summary: summary}}我同时配了智谱和讯飞星火的备用api_key通过环境变量切换。这么做的好处很实际万一DeepSeek服务不稳定改个环境变量就能切到别的厂商API服务不会因为单一依赖而宕机。厂商的免费额度各不相同个人项目完全可以在不同服务商之间周转。4. 常见问题与排查技巧实录4.1 AI生成代码的坑版本、依赖与幻觉这一节全是实战经验。AI生成代码最大的坑别看它写出来的代码行云流水幻觉无处不在。我这次遇到的经典问题全列出来版本错位AI给了pydantic 1.x风格的代码但装出来的是pydantic 2.x导致所有模型声明报错。排查时ImportError和AttributeError满天飞。后来我用一条命令全部锁定让AI在requirements.txt里标注pydantic2.5.2这种精确版本再装就稳了。不存在的函数AI引用了一个fastapi.something里的函数一执行发现这个模块根本没有这个函数。查证后发现是AI把某个旧版本或它自己脑补的内容当成了事实。这类问题只能靠跑测试暴露没有捷径。库用错我需要一个限流功能AI推荐了db.rate_limit()这么个库在我明确指定用slowapi之前它一直给我一个我搜都搜不到的东西。所以给AI指定的核心依赖一定要具体。权限逻辑混淆AI初版的注册接口和登录接口权限依赖搞反了登录接口居然公开也能创建用户。这是我review每个接口权限时发现的属于业务逻辑层面的错误自动化测试大概率测不出来。有个习惯强烈建议建立AI生成的代码每一段都要自己跑一遍最小用例验证。别因为对话窗口里AI回复这个代码肯定没问题就放松警惕。AI的自信跟代码质量没有正相关。4.2 API调试三板斧与性能优化调试API时我主要用三件套。第一件是curl快速验证接口通不通curl -X POST http://127.0.0.1:8000/api/v1/users/login \ -H Content-Type: application/json \ -d {username: admin, password: 123456}第二件是直接动用FastAPI自带的/docs页面鼠标点点就能测试每个接口还能看请求参数和响应格式这个功能在项目开发阶段比任何API调试工具都好用。第三件是写了个简单的Python脚本模拟用户注册、登录、写笔记、调用AI总结的完整链路每次改完代码就跑一遍做回归验证。性能优化我心里有个优先级清单。这个阶段的服务用户量可能就几个最大的性能风险不是代码慢而是你花了太多时间优化根本不存在的瓶颈。实际值得做的就两件事给高频接口加Redis缓存给数据库慢查询加索引。笔记列表接口我就用了Redis缓存TTL设60秒配合数据库索引当前体量下响应时间稳定在50毫秒以内。API调用量这个指标记得在服务里打点统计一下不然你完全不知道哪个接口在消耗资源。4.3 安全与合规个人项目也需要底线安全配置不能因为项目小就放水。这次把踩过的安全相关坑集中复盘一下API Key的存储永远不要提交到Git仓库.env文件一定要进.gitignore。如果API Key泄露立刻吊销重新签发别存侥幸心理。接口输入校验AI生成的代码可能没限制请求体大小用户给它传一个100MB的超大文本后端直接就宕了。我加了内容长度校验超了就拒绝。限流必须做对公开接口和需要调大模型API的接口限流是硬性要求。大模型API有成本不限流的话一个恶意的循环调用就能让你欠费。我在AI接口上用了slowapi限流每个API Key每分钟最多调5次代码如下from slowapi import Limiter from slowapi.util import get_remote_address limiter Limiter(key_funcget_remote_address) app.state.limiter limiter router.post(/ai/summarize) limiter.limit(5/minute) def summarize_note(request: Request, payload: NoteSummarizeRequest): ...第三方大模型API的合规使用调用DeepSeek、智谱这些服务时要仔细阅读服务商的使用条款注意数据隐私边界。个人项目尤其别把测试用的垃圾数据往生产环境的大模型API里送如果内容需要脱敏先处理好再上送。如果你想把这个项目继续往后做我建议下一步把AI能力从单次总结扩展成真正的AI Agent让它能根据笔记内容自动规划写作大纲、定时生成日报通过工具调用把更多能力串起来。这个方向我自己还在折腾等跑通了再开一篇单独写。这次的整条链路走到现在从提示词设计到代码验证、从容器部署到安全加固每一环都在告诉你一件事AI可以把一个项目的起点压得极低但真正决定它能走多远的始终是你自己的判断力。
前阵子想给个人项目加一套API服务把数据接口暴露给小程序和前端用。正好这两年AI编程工具越来越能打DeepSeek、智谱、讯飞星火这类大模型API的免费额度也够个人项目折腾我就干脆做了次彻底的实战全程让AI当主力从零把一个API服务搭出来能注册、能写数据、能部署上线还接进了大模型能力。这篇文章是这次实践的完整还原从需求拆解、技术选型、提示词设计、代码生成、调试部署到踩坑记录都有。想用AI快速落地后端服务的人或者好奇AI生成的代码到底能不能直接上线的这篇应该能给你一份能参考的答案。1. 项目整体设计与思路拆解1.1 为什么我会想到用AI来搭API服务先交代下背景。我有一个AI灵感笔记的小想法用户把碎片想法存下来隔段时间让大模型帮忙总结、提炼关键词、甚至扩展成文章大纲。说白了就是一套标准的后端服务要管用户、管笔记数据还要跟大模型API打交道。传统做法里这种项目绕不开一堆重复劳动项目脚手架、数据库配置、CURD接口、鉴权逻辑、部署配置每一样都得查文档、试错没个两三天出不来能跑通的东西。AI在这个过程里扮演的不只是代码生成器更像一个随叫随到的结对编程搭档。我列一下它在我这次项目里实际承担的工作生成项目雏形一个提示词让它输出FastAPI完整骨架包括依赖文件、启动脚本、路由结构省掉了我对着文档翻半天的工夫。批量产出重复代码用户管理、笔记增删改查这类模式固定的接口AI几秒钟就能给出一套能改着用的实现。当人肉文档记不清某个中间件怎么配、某个依赖参数怎么写时直接问AI比翻官方文档快得多。代码审查帮手写完核心逻辑后让AI换一个角度挑毛病往往能发现边界条件没考虑、异常没捕获这类问题。但这不代表AI能包办一切。我这次最大的体会是它擅长的是把话变成代码而什么话该说、怎么说、说的边界在哪仍然得你自己拿主意。业务逻辑的合理性、数据模型的设计、安全边界的划分这些基本功AI替代不了它只是帮你把从想法到初稿的时间压缩到原来的十分之一。1.2 技术选型为什么最终选择了FastAPI MySQL Redis技术选型是一个API服务的起点。我在项目开始前做了个对比把几个主流方案摊开来看框架性能类型校验自动文档异步支持上手难度FastAPI高接近GoPydantic内置自动生成开箱即用原生异步中等Flask中需自己加库需额外配置需额外插件低Express(Node)中高需额外配置需额外配置原生异步中等最终选了FastAPI理由很实在它自带自动交互式文档浏览器打开/docs就能调试每个接口这对AI生成代码后的验证环节太重要了参数校验、响应模型这些和Pydantic深度集成相当于类型安全直接内置性能表现也完全够个人项目用。数据层选了MySQL Redis的组合。MySQL是业务数据的存储核心成熟稳定社区资料多就算AI生成的SQL有问题排查成本也最低Redis主要承担两件事一是给热点接口做缓存二是后面做API限流时存计数器。这里也能看出技术选型的一个原则不追新、不炫技选择自己最熟悉、排错资料最多的那一套AI侧的容错率反而更高。顺便说一句大模型API的选型。这次项目里要接AI总结功能我在DeepSeek、智谱GLM、讯飞星火之间做了对比。它们都提供免费测试额度对个人项目来说足够用调用方式也统一兼容OpenAI的SDK意味着AI生成的调用代码可以在不同厂商间无缝切换。我最终把大模型API的接入抽象成了一层独立服务厂商的api_key和base_url全部走环境变量方便随时切换。这类细节建议你在动手前就想好不然AI生成的代码里到处硬编码后期维护会很痛苦。2. 核心细节解析与实操要点2.1 AI辅助编码的关键提示词设计很多人让AI写代码结果拿回来的东西没法用问题往往不在AI而在提示词。拿帮我写个API这种需求去问AI它能给你一百种天马行空的答案。我这次实践下来发现一个合格的后端提示词至少包含四个维度的信息角色设定、任务描述、约束条件、输出格式。举个实际例子。我在项目开始时给AI的提示词大致是这样你是一位资深的Python后端工程师。请基于FastAPI生成一个API服务的项目骨架要求如下 1. 使用Python 3.10FastAPI 0.100SQLAlchemy 2.0PyMySQL 2. 项目结构分为app/main.py、app/models.py、app/schemas.py、app/routers/ 3. 实现用户注册和登录接口密码使用bcrypt加密存储 4. 实现笔记的增删改查接口接口路径遵循RESTful规范 5. 所有接口的响应统一为{code:0,data:...}格式 6. 请逐个文件输出完整代码并在关键位置添加注释。这个提示词的效果和我之前随手写的帮我搞一个笔记API完全是两个量级。角色限定让AI用后端工程师的标准来写代码任务描述把要做什么说清楚约束条件把依赖版本和实现方式都钉死了输出格式则让结果更可控。这里有几个我踩过的坑新手尤其容易栽进去没锁版本AI默认生成的依赖可能用了它训练数据里最热门的版本但版本号和实际安装到的最新版经常对不上。比如pydantic从v1升到v2后很多写法直接废了。我的做法是让AI每次生成requirements.txt时必须标注测试过的版本组合然后装完后立刻跑一遍测试验证。需求没写边界只说做个删除笔记接口AI给的可能是物理删除但业务上你可能希望逻辑删除。这类业务规则不写进去AI猜不出来的。没让它解释代码AI输出代码后追加一句请解释一下认证依赖函数的执行流程。逼它解释就是在帮你做代码审查很多隐藏的逻辑坑会在这一步暴露出来。2.2 API设计规范与数据库建模动手写代码前先把接口画出来。这里不一定要画正经的API文档哪怕在备忘录里列一个接口清单也够用了。我给这个AI灵感笔记服务设计的核心接口是这样方法路径功能权限POST/api/v1/users/register用户注册公开POST/api/v1/users/login用户登录公开GET/api/v1/notes获取笔记列表需登录POST/api/v1/notes创建笔记需登录GET/api/v1/notes/{id}获取笔记详情需登录PATCH/api/v1/notes/{id}更新笔记需登录DELETE/api/v1/notes/{id}删除笔记需登录POST/api/v1/ai/summarizeAI总结笔记需登录路径规划遵循RESTful直觉资源用名词复数操作由HTTP方法表达版本号直接放进路径前缀/api/v1避免未来接口升级时打挂老客户端。数据库建模这部分我让AI给出第一版设计然后自己做了review。AI生成的初版表结构有个典型问题它给我加了购买会员之类的多余字段差点把方向带偏。我最终定下来的核心就两张表CREATE TABLE users ( id BIGINT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(64) UNIQUE NOT NULL, password_hash VARCHAR(128) NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE notes ( id BIGINT AUTO_INCREMENT PRIMARY KEY, user_id BIGINT NOT NULL, title VARCHAR(200) NOT NULL, content TEXT NOT NULL, summary TEXT, status TINYINT DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_user_id (user_id), CONSTRAINT fk_notes_user FOREIGN KEY (user_id) REFERENCES users(id) );表结构里有个经验值得单独说给notes.user_id加了普通索引就够了个人项目的体量完全不需要搞什么分区表、读写分离。无数人会犯的错误就是脑子里装着大厂架构一上来就堆组件结果运维成本比开发成本还高。我在这个项目里时刻提醒自己能用单表解决的绝不拆表。3. 实操过程与核心环节实现3.1 用AI生成项目骨架并跑通选好方案、理清接口就可以请AI动工了。我用的是DeepSeek的网页对话窗口先按前文的提示词让它输出项目骨架。AI陆续给了几段文件这里我只贴核心的app/main.py你感受下AI生成的代码质量from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.routers import users, notes, ai app FastAPI( titleAI灵感笔记API, description一个结合大模型能力的个人笔记服务, version1.0.0, ) app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], ) app.include_router(users.router, prefix/api/v1, tags[用户]) app.include_router(notes.router, prefix/api/v1, tags[笔记]) app.include_router(ai.router, prefix/api/v1, tags[AI能力]) app.get(/health) def health_check(): return {status: ok}这段代码质量挺高但有一个安全细节需要你警觉allow_origins[*]这种配置如果做带鉴权的API是不可接受的等于是允许任意前端读取任意接口数据。我拿到代码后立刻改了只留了自己小程序的域名。这就是前面说的AI负责产出你负责把关。把文件逐个保存到本地后用一条命令跑起来看效果pip install -r requirements.txt uvicorn app.main:app --reload --port 8000浏览器打开http://127.0.0.1:8000/docs看到Swagger文档页面出现的瞬间项目就算正式活了。这一步的体验对比传统开发太明显了以前光配项目结构、装依赖、处理启动报错就得耗掉一下午现在AI十分钟给了初稿我只是做验证和修正。3.2 数据库接入与数据模型迁移项目骨架跑通后下一步接入数据库。AI生成的SQLAlchemy模型基本能用稍微改改就直接上线了。app/models.py里的核心内容是这样from sqlalchemy import Column, BigInteger, String, Text, DateTime, func from sqlalchemy.orm import declarative_base Base declarative_base() class User(Base): __tablename__ users id Column(BigInteger, primary_keyTrue, autoincrementTrue) username Column(String(64), uniqueTrue, nullableFalse) password_hash Column(String(128), nullableFalse) created_at Column(DateTime, defaultfunc.now()) class Note(Base): __tablename__ notes id Column(BigInteger, primary_keyTrue, autoincrementTrue) user_id Column(BigInteger, nullableFalse) title Column(String(200), nullableFalse) content Column(Text, nullableFalse) summary Column(Text) status Column(BigInteger, default1) created_at Column(DateTime, defaultfunc.now()) updated_at Column(DateTime, defaultfunc.now(), onupdatefunc.now())数据库连接这一块我用的是SQLAlchemy 2.0风格连接串放在环境变量里读取避免把账号密码写进代码。数据库初始化也不需要额外工具启动时执行一次建表就能跑省掉了Migrations的复杂度个人项目完全够用from sqlalchemy.orm import sessionmaker from sqlalchemy import create_engine import os DATABASE_URL os.getenv( DATABASE_URL, mysqlpymysql://root:password127.0.0.1:3306/ai_notes?charsetutf8mb4 ) engine create_engine(DATABASE_URL, pool_size10, pool_recycle3600) SessionLocal sessionmaker(bindengine, autoflushFalse, autocommitFalse)这里有个值得展开的细节charsetutf8mb4。如果漏掉这个参数MySQL的默认字符集会让你存的emoji全部变成问号。AI在第一次给我的连接串里就没加这个参数我是在测试写入一个带表情符号的笔记标题时发现的。这种细节就是典型的AI不知道业务上下文但你知道的地方。3.3 鉴权与API密钥管理一个对外暴露的API服务最不能省的就是身份识别。我在这个项目里选择了API Key方案而不是JWT主要考虑是把服务给我的小程序用API Key的方式更直观、好调试——小程序请求时带一个X-API-Key请求头后端校验通过就放行。登录接口先验证用户名和密码验证通过后签发一个API Key给客户端留存。签发逻辑的AI初稿用的是uuid4().hex生成一段随机字符串并存库这个方案我认可但加了一个安全整改密钥不做明文存储只存它的SHA256哈希值。这样即使数据库被拖走攻击者也拿不到可用的Key。核心代码如下import hashlib import secrets def generate_api_key(): return secrets.token_hex(32) def hash_api_key(api_key: str) - str: return hashlib.sha256(api_key.encode()).hexdigest()校验依赖用FastAPI的Depends机制写了个通用函数所有需要登录的接口直接声明依赖就行from fastapi import Depends, HTTPException, Security from fastapi.security import APIKeyHeader api_key_header APIKeyHeader(nameX-API-Key, auto_errorFalse) def verify_api_key(api_key: str Security(api_key_header)): if not api_key: raise HTTPException(status_code401, detail缺少API Key) digested hash_api_key(api_key) # 到数据库查询 digested 是否存在存在则返回用户信息 ...密码存储用的是bcrypt库AI生成代码时默认用了这个方案我查了下确认是当下最稳妥的选择之一就没改。这里要提醒的是一定不能让AI自己发明一个加密算法——曾经有个AI生成代码里用了自定义的异或运算来加密密码那跟明文没区别。安全相关的功能必须限定AI用业界公认的成熟方案。3.4 容器化部署与域名上线本地能跑只是开始真正常用的API得部署到服务器上才能生效。我买了台2核4G的轻量服务器系统和云服务商没有特别要求你按自己熟悉的来就行。部署方案直接选择Docker Compose把应用和数据库一起编排这样迁移服务器时能整个环境一起搬走。AI在这里帮我生成了两个文件效果比手写快得多。先看DockerfileFROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]再看docker-compose.ymlversion: 3.9 services: api: build: . ports: - 8000:8000 environment: - DATABASE_URLmysqlpymysql://root:passworddb:3306/ai_notes?charsetutf8mb4 - DEEPSEEK_API_KEY${DEEPSEEK_API_KEY} depends_on: - db db: image: mysql:8.0 environment: - MYSQL_ROOT_PASSWORDpassword volumes: - mysql_data:/var/lib/mysql volumes: mysql_data:部署上线时我踩了一个非常典型的坑AI生成的环境变量里数据库地址写的是127.0.0.1这在Docker网络里是不通的因为api容器和db容器不是一个网络空间。连接串必须改成服务名db也就是上面compose文件里DATABASE_URL中写的db:3306。这个坑不止一次出现在AI生成的项目里你如果也是用Docker部署务必检查数据库地址写的是不是容器服务名而不是回环地址。部署命令很简单服务器上安装好Docker后docker compose up -d --build启动成功后再用Nginx做反向代理给服务域名配上HTTPS证书。这些配置我在网上找了模板改了一下完全不需要AI参与。至此一个真正能通过HTTPS访问的API服务就上线了。3.5 接入大模型API让服务学会思考到了这个项目最核心的功能点让笔记服务拥有AI能力。我的需求是提供一个接口客户端传入一篇笔记内容后端调用大模型API返回总结和几个关键词。这个功能在技术层面正好可以验证一件事第三方大模型API的接入到底有多简单。先后装好依赖pip install openai然后写一个独立的大模型客户端模块。这里有个好消息是DeepSeek、智谱、讯飞星火都兼容OpenAI SDK格式所以调用代码可以非常统一from openai import OpenAI import os client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(LLM_BASE_URL, https://api.deepseek.com), ) def summarize(content: str) - str: resp client.chat.completions.create( modelos.getenv(LLM_MODEL, deepseek-chat), messages[ {role: system, content: 你是一名称职的编辑请对用户输入的内容进行总结提炼出不超过5个关键词并以JSON格式返回。}, {role: user, content: content}, ], temperature0.3, ) return resp.choices[0].message.content这段代码里有两个值得留意的点。第一temperature设置成了0.3因为总结场景我们希望输出稳定、可复现温度太高会得到每次都不一样的花式总结。第二system提示词里明确要求返回JSON格式这是让大模型输出结构化数据最省事的做法比自己写正则从自由文本里抠关键词靠谱得多。接口层再包一层AI生成的路由代码稍作修改就能用router.post(/ai/summarize) def summarize_note(payload: NoteSummarizeRequest, user: User Depends(verify_api_key)): summary summarize(payload.content) return {code: 0, data: {summary: summary}}我同时配了智谱和讯飞星火的备用api_key通过环境变量切换。这么做的好处很实际万一DeepSeek服务不稳定改个环境变量就能切到别的厂商API服务不会因为单一依赖而宕机。厂商的免费额度各不相同个人项目完全可以在不同服务商之间周转。4. 常见问题与排查技巧实录4.1 AI生成代码的坑版本、依赖与幻觉这一节全是实战经验。AI生成代码最大的坑别看它写出来的代码行云流水幻觉无处不在。我这次遇到的经典问题全列出来版本错位AI给了pydantic 1.x风格的代码但装出来的是pydantic 2.x导致所有模型声明报错。排查时ImportError和AttributeError满天飞。后来我用一条命令全部锁定让AI在requirements.txt里标注pydantic2.5.2这种精确版本再装就稳了。不存在的函数AI引用了一个fastapi.something里的函数一执行发现这个模块根本没有这个函数。查证后发现是AI把某个旧版本或它自己脑补的内容当成了事实。这类问题只能靠跑测试暴露没有捷径。库用错我需要一个限流功能AI推荐了db.rate_limit()这么个库在我明确指定用slowapi之前它一直给我一个我搜都搜不到的东西。所以给AI指定的核心依赖一定要具体。权限逻辑混淆AI初版的注册接口和登录接口权限依赖搞反了登录接口居然公开也能创建用户。这是我review每个接口权限时发现的属于业务逻辑层面的错误自动化测试大概率测不出来。有个习惯强烈建议建立AI生成的代码每一段都要自己跑一遍最小用例验证。别因为对话窗口里AI回复这个代码肯定没问题就放松警惕。AI的自信跟代码质量没有正相关。4.2 API调试三板斧与性能优化调试API时我主要用三件套。第一件是curl快速验证接口通不通curl -X POST http://127.0.0.1:8000/api/v1/users/login \ -H Content-Type: application/json \ -d {username: admin, password: 123456}第二件是直接动用FastAPI自带的/docs页面鼠标点点就能测试每个接口还能看请求参数和响应格式这个功能在项目开发阶段比任何API调试工具都好用。第三件是写了个简单的Python脚本模拟用户注册、登录、写笔记、调用AI总结的完整链路每次改完代码就跑一遍做回归验证。性能优化我心里有个优先级清单。这个阶段的服务用户量可能就几个最大的性能风险不是代码慢而是你花了太多时间优化根本不存在的瓶颈。实际值得做的就两件事给高频接口加Redis缓存给数据库慢查询加索引。笔记列表接口我就用了Redis缓存TTL设60秒配合数据库索引当前体量下响应时间稳定在50毫秒以内。API调用量这个指标记得在服务里打点统计一下不然你完全不知道哪个接口在消耗资源。4.3 安全与合规个人项目也需要底线安全配置不能因为项目小就放水。这次把踩过的安全相关坑集中复盘一下API Key的存储永远不要提交到Git仓库.env文件一定要进.gitignore。如果API Key泄露立刻吊销重新签发别存侥幸心理。接口输入校验AI生成的代码可能没限制请求体大小用户给它传一个100MB的超大文本后端直接就宕了。我加了内容长度校验超了就拒绝。限流必须做对公开接口和需要调大模型API的接口限流是硬性要求。大模型API有成本不限流的话一个恶意的循环调用就能让你欠费。我在AI接口上用了slowapi限流每个API Key每分钟最多调5次代码如下from slowapi import Limiter from slowapi.util import get_remote_address limiter Limiter(key_funcget_remote_address) app.state.limiter limiter router.post(/ai/summarize) limiter.limit(5/minute) def summarize_note(request: Request, payload: NoteSummarizeRequest): ...第三方大模型API的合规使用调用DeepSeek、智谱这些服务时要仔细阅读服务商的使用条款注意数据隐私边界。个人项目尤其别把测试用的垃圾数据往生产环境的大模型API里送如果内容需要脱敏先处理好再上送。如果你想把这个项目继续往后做我建议下一步把AI能力从单次总结扩展成真正的AI Agent让它能根据笔记内容自动规划写作大纲、定时生成日报通过工具调用把更多能力串起来。这个方向我自己还在折腾等跑通了再开一篇单独写。这次的整条链路走到现在从提示词设计到代码验证、从容器部署到安全加固每一环都在告诉你一件事AI可以把一个项目的起点压得极低但真正决定它能走多远的始终是你自己的判断力。
