283 lines
12 KiB
Markdown
283 lines
12 KiB
Markdown
# 开发流程
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [docker-compose.yml](file://docker-compose.yml)
|
||
- [backend/Dockerfile](file://backend/Dockerfile)
|
||
- [frontend/Dockerfile](file://frontend/Dockerfile)
|
||
- [backend/requirements.txt](file://backend/requirements.txt)
|
||
- [frontend/package.json](file://frontend/package.json)
|
||
- [tests/conftest.py](file://tests/conftest.py)
|
||
- [backend/alembic.ini](file://backend/alembic.ini)
|
||
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
|
||
- [frontend/README.md](file://frontend/README.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向GEO项目的开发团队，提供一套完整的开发流程规范，涵盖Git分支策略与工作流、代码审查流程、版本发布管理、持续集成/持续部署（CI/CD）配置说明，以及开发环境搭建与团队协作最佳实践。内容基于仓库现有技术栈与容器化配置进行设计，确保前后端协同开发、数据库迁移与测试流程可追溯、可复现。
|
||
|
||
## 项目结构
|
||
GEO采用前后端分离与容器编排的组织方式：
|
||
- 前端：Next.js 14 应用，使用TypeScript与TailwindCSS，开发端口3000。
|
||
- 后端：FastAPI + Uvicorn，使用异步数据库驱动与Redis缓存，开发端口8000。
|
||
- 数据层：PostgreSQL 15 + Redis 7，通过Docker Compose统一编排。
|
||
- 迁移与版本管理：Alembic用于数据库迁移脚本生成与执行。
|
||
- 测试：pytest + pytest-asyncio，配合HTTP异步客户端与依赖注入覆盖。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "本地开发环境"
|
||
FE["前端服务<br/>Next.js 3000"]
|
||
BE["后端服务<br/>FastAPI 8000"]
|
||
DB["数据库<br/>PostgreSQL 15"]
|
||
RC["缓存<br/>Redis 7"]
|
||
end
|
||
FE --> |"HTTP 请求"| BE
|
||
BE --> DB
|
||
BE --> RC
|
||
```
|
||
|
||
图表来源
|
||
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
|
||
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
|
||
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
|
||
|
||
章节来源
|
||
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
|
||
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
|
||
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
|
||
|
||
## 核心组件
|
||
- 前端工程
|
||
- 使用Next.js应用路由与API路由，开发脚本与构建脚本在package.json中定义。
|
||
- TypeScript与ESLint配置位于前端根目录，保证类型安全与代码风格一致。
|
||
- 后端工程
|
||
- FastAPI应用入口与异步数据库连接，依赖通过requirements.txt集中管理。
|
||
- Alembic迁移配置与初始迁移脚本存在，支持数据库演进。
|
||
- 测试工程
|
||
- pytest会话级fixture用于屏蔽真实定时任务，提供模拟用户与认证头，便于快速集成测试。
|
||
- 容器化与编排
|
||
- Dockerfile分别构建前后端镜像；docker-compose统一启动数据库、缓存、后端与前端服务，并设置健康检查与依赖顺序。
|
||
|
||
章节来源
|
||
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
|
||
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
|
||
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)
|
||
- [backend/alembic.ini:1-134](file://backend/alembic.ini#L1-L134)
|
||
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
|
||
|
||
## 架构总览
|
||
下图展示从浏览器到后端API再到数据库与缓存的整体调用链路，体现开发环境中的典型请求路径与数据流向。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Browser as "浏览器"
|
||
participant Frontend as "前端应用"
|
||
participant Backend as "后端API"
|
||
participant DB as "数据库"
|
||
participant Cache as "缓存"
|
||
Browser->>Frontend : "访问页面"
|
||
Frontend->>Backend : "发起HTTP请求"
|
||
Backend->>DB : "查询/写入数据"
|
||
DB-->>Backend : "返回结果"
|
||
Backend->>Cache : "读取/更新缓存"
|
||
Cache-->>Backend : "返回缓存命中/更新"
|
||
Backend-->>Frontend : "响应JSON"
|
||
Frontend-->>Browser : "渲染页面"
|
||
```
|
||
|
||
图表来源
|
||
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
|
||
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
|
||
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
|
||
|
||
## 详细组件分析
|
||
|
||
### Git 分支策略与工作流
|
||
建议采用Git Flow变体，结合Feature分支与Release分支，确保开发与发布的可控性与可追溯性：
|
||
|
||
- 主分支
|
||
- main：仅允许来自release或hotfix的合并，保持生产就绪状态。
|
||
- develop：集成各功能特性，作为后续release的基线。
|
||
- 功能分支（feature）
|
||
- 命名：feature/<issue-id>-短描述
|
||
- 从develop切出，完成后合并回develop并删除分支。
|
||
- 预发布分支（release）
|
||
- 从develop切出，进行最终修复与回归测试，完成后合并至main与develop并打标签。
|
||
- 热修复分支（hotfix）
|
||
- 从main切出，紧急修复后同时合并回main与develop。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["开始"] --> B["创建功能分支 feature/<id>-desc"]
|
||
B --> C["提交到功能分支"]
|
||
C --> D{"完成开发？"}
|
||
D --> |否| C
|
||
D --> |是| E["推送并发起PR到 develop"]
|
||
E --> F["代码审查与测试通过"]
|
||
F --> G["合并到 develop 并删除分支"]
|
||
G --> H["准备 release 分支"]
|
||
H --> I["最终测试与修复"]
|
||
I --> J["合并到 main 与 develop 并打标签"]
|
||
```
|
||
|
||
说明
|
||
- PR需关联Issue，确保需求可追溯。
|
||
- 合并前必须通过本地与CI测试，且无冲突。
|
||
|
||
### 代码审查流程
|
||
- Pull Request 模板
|
||
- 必填字段：标题（简述变更）、类型（修复/特性/重构/文档）、影响范围、变更摘要、测试要点、风险评估与回滚预案。
|
||
- 关联信息：关联Issue编号、相关PR链接、模块负责人。
|
||
- 审查标准
|
||
- 正确性：单元测试与集成测试覆盖率达标；边界条件与异常处理完备。
|
||
- 可读性：命名规范、注释清晰、函数长度与复杂度合理。
|
||
- 兼容性：接口变更需向后兼容或提供迁移方案；数据库变更需可逆。
|
||
- 安全性：输入校验、权限控制、敏感信息脱敏。
|
||
- 合并要求
|
||
- 至少一名审查者批准。
|
||
- CI流水线通过。
|
||
- 无未解决评论。
|
||
- 合并后清理功能分支。
|
||
|
||
### 版本发布管理
|
||
- 语义化版本控制
|
||
- 主版本号：破坏性变更
|
||
- 次版本号：新增兼容功能
|
||
- 修订号：修复兼容问题
|
||
- 变更日志维护
|
||
- 按版本记录：新增、修复、改进、废弃与破坏性变更。
|
||
- 引用相关PR与Issue，便于追溯。
|
||
- 发布标签
|
||
- 在release分支合并后于main打标签，格式：vMAJOR.MINOR.REVISION。
|
||
- 为每个版本生成对应Docker镜像并推送到制品库。
|
||
|
||
### 持续集成/持续部署（CI/CD）
|
||
当前仓库未包含CI配置文件，建议在CI系统中实现以下流程：
|
||
- 触发条件
|
||
- push到develop/release/main/hotfix或打开PR时触发。
|
||
- 步骤
|
||
- 安装依赖：后端pip、前端npm ci。
|
||
- 代码质量：后端使用ruff/black，前端使用ESLint。
|
||
- 单元测试：pytest与pytest-asyncio，生成覆盖率报告。
|
||
- 容器构建：分别构建后端与前端镜像。
|
||
- 健康检查：启动docker-compose并在数据库/缓存健康后运行端到端测试。
|
||
- 制品归档：上传测试报告与镜像。
|
||
- 部署
|
||
- develop：自动部署到预发布环境。
|
||
- release：手动审批后部署到生产环境。
|
||
- hotfix：自动部署到生产并回补到develop。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
S["提交/PR触发"] --> L["安装依赖与代码质量检查"]
|
||
L --> T["运行单元测试与覆盖率"]
|
||
T --> B["构建后端/前端镜像"]
|
||
B --> D["启动容器并健康检查"]
|
||
D --> E["端到端测试"]
|
||
E --> R{"是否发布？"}
|
||
R --> |否| P["归档制品与报告"]
|
||
R --> |是| DEP["部署到目标环境"]
|
||
DEP --> TAG["打标签并发布"]
|
||
```
|
||
|
||
说明
|
||
- 以上为通用CI/CD流程建议，具体实现需在CI平台配置相应作业与工件。
|
||
|
||
### 开发环境搭建与团队协作最佳实践
|
||
- 环境准备
|
||
- 安装Docker与Docker Compose，确保端口未被占用。
|
||
- 复制示例环境变量文件并按需调整数据库与缓存参数。
|
||
- 启动步骤
|
||
- 后端：进入backend目录，安装依赖并启动服务；或使用docker-compose一键启动。
|
||
- 前端：进入frontend目录，安装依赖并启动开发服务器。
|
||
- 团队协作
|
||
- 统一代码风格：后端使用ruff/black，前端使用ESLint/TailwindCSS。
|
||
- 提交信息规范：type(scope): subject，如feat(api): 新增用户认证接口。
|
||
- 冲突解决：优先rebase保持线性历史，必要时使用merge并保留解决记录。
|
||
- 文档同步：变更涉及用户界面或API时同步更新README与变更日志。
|
||
|
||
章节来源
|
||
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
|
||
- [frontend/README.md:1-37](file://frontend/README.md#L1-L37)
|
||
|
||
## 依赖关系分析
|
||
- 技术栈依赖
|
||
- 前端：Next.js、React、TypeScript、TailwindCSS、Radix UI等。
|
||
- 后端：FastAPI、SQLAlchemy、AsyncPG、Alembic、Redis、APScheduler、Playwright等。
|
||
- 容器与编排
|
||
- docker-compose定义了数据库、缓存、后端与前端服务的依赖关系与健康检查。
|
||
- 测试依赖
|
||
- pytest与pytest-asyncio用于异步测试；ASGI传输用于HTTP客户端测试；依赖注入覆盖用于模拟认证上下文。
|
||
|
||
```mermaid
|
||
graph LR
|
||
FE["前端应用"] --> |HTTP| BE["后端API"]
|
||
BE --> DB["PostgreSQL"]
|
||
BE --> RC["Redis"]
|
||
BE --> AL["Alembic 迁移"]
|
||
TEST["pytest 测试"] --> BE
|
||
```
|
||
|
||
图表来源
|
||
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
|
||
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)
|
||
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)
|
||
|
||
章节来源
|
||
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
|
||
- [tests/conftest.py:1-71](file://tests/conftest.py#L1-L71)
|
||
- [backend/alembic.ini:1-134](file://backend/alembic.ini#L1-L134)
|
||
|
||
## 性能考虑
|
||
- 数据库
|
||
- 使用异步驱动与连接池，避免阻塞；迁移脚本应最小化DDL变更，避免长事务锁表。
|
||
- 缓存
|
||
- 合理设置TTL与键空间，热点数据优先缓存；定期清理过期键。
|
||
- API
|
||
- 控制响应大小与分页；对高频接口启用缓存；限制并发与速率。
|
||
- 前端
|
||
- 图片与静态资源优化；按需加载；TailwindCSS类名避免冗余。
|
||
- 容器
|
||
- 使用多阶段构建减少镜像体积；健康检查降低重启时间；资源限制防止资源争用。
|
||
|
||
## 故障排查指南
|
||
- 本地服务无法启动
|
||
- 检查端口占用与防火墙；确认数据库与缓存服务已健康运行。
|
||
- 数据库迁移失败
|
||
- 查看Alembic配置与URL；确认迁移脚本语法正确；必要时回滚至上一版本。
|
||
- 测试异常
|
||
- 确认pytest会话级fixture已正确屏蔽定时任务；检查依赖注入覆盖是否生效。
|
||
- 前后端联调失败
|
||
- 核对CORS与代理配置；确认API路由与鉴权头正确传递。
|
||
|
||
章节来源
|
||
- [docker-compose.yml:16-20](file://docker-compose.yml#L16-L20)
|
||
- [docker-compose.yml:30-34](file://docker-compose.yml#L30-L34)
|
||
- [backend/alembic.ini:86-89](file://backend/alembic.ini#L86-L89)
|
||
- [tests/conftest.py:19-25](file://tests/conftest.py#L19-L25)
|
||
|
||
## 结论
|
||
通过明确的分支策略、严格的代码审查流程、规范的版本发布管理与可落地的CI/CD实践，GEO项目能够在保障交付质量的同时提升团队协作效率。建议尽快在CI平台落地上述流程，并根据实际运行情况迭代优化。
|
||
|
||
## 附录
|
||
- 快速启动命令
|
||
- docker-compose：启动所有服务并进入交互模式。
|
||
- 前端：进入frontend目录，安装依赖后启动开发服务器。
|
||
- 后端：进入backend目录，安装依赖后启动Uvicorn服务。
|
||
- 参考文档
|
||
- Next.js官方文档与部署指南。
|
||
- FastAPI与SQLAlchemy异步数据库实践。
|
||
- Alembic迁移最佳实践。 |