1. 说在前面

• AI的迅猛发展，导致前端变成了一个高危行业，所以不得不向全栈工程师进发。当然，这也是未来的方向
• 所以将开发全栈项目的过程记录一下，方便查阅，也希望能帮到大家
• 目前项目已经顺利上线，当然也不是很复杂，前后端都是自己搞定，耗时3天，所以还是有一些参考价值的
• 本文由浅入深，也非常详细，有需要的话大家可以收藏关注一波
• 本项目是调用AI大模型的项目（通义千问，图像分析模型）

2. 前端技术栈

• uni-app (Vue 3) ： 跨平台框架，支持 H5、微信小程序、App
• Vite：快速开发服务器与构建
• Pinia：Vue 3 官方推荐状态管理库
• uni.request：uni-app 内置请求 API
• useLoginGuard：自定义 composable，基于 token 判断登录状态

3. 后端技术栈

1. 语言： Python 3.10+ 异步支持
2. Web 框架： FastAPI 高性能异步 API 框架
3. ORM： SQLAlchemy 2.x (async) 异步数据库操作
4. 数据库驱动： aiosqlite SQLite 异步驱动
5. 数据库： SQLite3 轻量级嵌入式数据库
6. 数据校验： Pydantic v2 请求/响应模型校验
7. HTTP 客户端： httpx 异步 HTTP 请求（调用 SSO、LLM、图像分析模型）
8. AI 模型： 通义千问 (qwen) OpenAI 兼容 Chat Completions API
9. 认证： MaxKey SSO OAuth2 授权码流程
10. 测试： pytest + pytest-asyncio 异步单元测试，22 个用例

4. 项目结构

├── app/                    # 前端 uni-app 工程
│   ├── src/
│   │   ├── api/            # HTTP 请求封装
│   │   ├── pages/          # 页面组件
│   │   ├── stores/         # Pinia 状态管理
│   │   ├── composables/    # 组合式函数
│   │   └── utils/          # 工具函数
│   ├── .env                # 前端环境变量
│   └── .env.example        # 前端环境变量模板
├── backend/                # 后端 FastAPI 工程
│   ├── app/
│   │   ├── routers/        # API 路由层
│   │   ├── services/       # 业务逻辑层
│   │   ├── config.py       # 配置管理
│   │   ├── database.py     # 数据库引擎
│   │   ├── models.py       # ORM 模型
│   │   ├── schemas.py      # 请求/响应 Schema
│   │   └── dependencies.py # 依赖注入（认证等）
│   ├── data/               # SQLite 数据库 & 上传文件
│   ├── db/                 # 数据库脚本（DDL）
│   ├── .env                # 后端环境变量
│   ├── .env.example        # 后端环境变量模板（开发）
│   ├── .env.test           # 测试环境模板
│   └── .env.prod           # 生产环境模板
├── scripts/                # 启动 & 部署脚本
├── docs/                   # 项目文档
└── AGENTS.md               # AI 编程助手指引

5. 项目的整个开发过程

1. 创建uniapp工程（这个比较简单）—— 前端
2. 接入状态管理能力（Pinia）—— 前端
3. 创建python目录

后端入口与基础结构
main.py
config.py
schemas.py
health.py
health_service.py

测试与依赖
test_health.py
requirements.txt
.env.example
README.md

文档与进度同步
PRD-20260427-python-api-init.md
README.md

4. 这个时候其实就可以启动前后端服务了，看到页面
5. 实现具体的业务逻辑

5. 需要注意的点

1. 可部署性（运维/DevOps 视角）
   启动脚本缺失 — 没有脚本意味着部署依赖口头传递，换个人就不会启动
   数据库无 DDL 脚本 — 代码里自动建表只适合开发，生产环境 DBA 需要审核 SQL 才能放行
   缺少多环境 profile — dev/test/prod 三套环境的配置混在一起或靠手动改，迟早出事故
   项目名残留模板名 — 部署后日志、监控看到的都是假名字，排查问题时造成混乱

2. 安全性（安全审计视角）
   LLM 提示词无反向约束 — AI 应用上线前必须做"红队测试"，防止被诱导输出不当内容
   .env 模板缺字段 — 新人拿到 .env.example 部署时发现少配置，服务启动就报错

3. 可维护性（团队协作视角）
   代码无注释 — 下一个接手的人（可能是半年后的你自己）完全看不懂意图
   无单元测试 — 每次改动都不知道有没有搞坏已有功能，修一个 bug 引入三个 bug
   废弃文档未清理 — 过期文件混在文档里，增加认知负担

• 改配置先改模板 在 .env 加了新字段，同步更新 .env.example、.env.test、.env.prod
• 改数据库先写 DDL 加表/加字段前，先在 db/migrations/ 写增量 SQL，再改 ORM 模型
• 写代码同时写测试 不要"等以后补"，写完一个接口立刻写对应的测试用例
• 提交前自查清单 console.log 清了没？硬编码的密钥？TODO 标记？测试跑过没？
• 保持文档同步 功能做完后更新 README 和 API.md，而不是攒到最后一起补

1. 希望本文能对大家有所帮助，如有错误，敬请指出
2. 原创不易，还请各位客官动动发财的小手支持一波（关注、评论、点赞、收藏）
3. 拜谢各位！后续将继续奉献优质好文