12 KiB

Raw Blame History

开发流程

**本文引用的文件** - [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)

简介

本文件面向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异步客户端与依赖注入覆盖。

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

图表来源

章节来源

核心组件

前端工程
- 使用Next.js应用路由与API路由，开发脚本与构建脚本在package.json中定义。
- TypeScript与ESLint配置位于前端根目录，保证类型安全与代码风格一致。
后端工程
- FastAPI应用入口与异步数据库连接，依赖通过requirements.txt集中管理。
- Alembic迁移配置与初始迁移脚本存在，支持数据库演进。
测试工程
- pytest会话级fixture用于屏蔽真实定时任务，提供模拟用户与认证头，便于快速集成测试。
容器化与编排
- Dockerfile分别构建前后端镜像；docker-compose统一启动数据库、缓存、后端与前端服务，并设置健康检查与依赖顺序。

章节来源

架构总览

下图展示从浏览器到后端API再到数据库与缓存的整体调用链路，体现开发环境中的典型请求路径与数据流向。

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 : "渲染页面"

图表来源

详细组件分析

Git 分支策略与工作流

建议采用Git Flow变体，结合Feature分支与Release分支，确保开发与发布的可控性与可追溯性：

主分支
- main：仅允许来自release或hotfix的合并，保持生产就绪状态。
- develop：集成各功能特性，作为后续release的基线。
功能分支（feature）
- 命名：feature/-短描述
- 从develop切出，完成后合并回develop并删除分支。
预发布分支（release）
- 从develop切出，进行最终修复与回归测试，完成后合并至main与develop并打标签。
热修复分支（hotfix）
- 从main切出，紧急修复后同时合并回main与develop。

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。

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与变更日志。

章节来源

依赖关系分析

技术栈依赖
- 前端：Next.js、React、TypeScript、TailwindCSS、Radix UI等。
- 后端：FastAPI、SQLAlchemy、AsyncPG、Alembic、Redis、APScheduler、Playwright等。
容器与编排
- docker-compose定义了数据库、缓存、后端与前端服务的依赖关系与健康检查。
测试依赖
- pytest与pytest-asyncio用于异步测试；ASGI传输用于HTTP客户端测试；依赖注入覆盖用于模拟认证上下文。

graph LR
FE["前端应用"] --> |HTTP| BE["后端API"]
BE --> DB["PostgreSQL"]
BE --> RC["Redis"]
BE --> AL["Alembic 迁移"]
TEST["pytest 测试"] --> BE

图表来源

章节来源

性能考虑

数据库
- 使用异步驱动与连接池，避免阻塞；迁移脚本应最小化DDL变更，避免长事务锁表。
缓存
- 合理设置TTL与键空间，热点数据优先缓存；定期清理过期键。
API
- 控制响应大小与分页；对高频接口启用缓存；限制并发与速率。
前端
- 图片与静态资源优化；按需加载；TailwindCSS类名避免冗余。
容器
- 使用多阶段构建减少镜像体积；健康检查降低重启时间；资源限制防止资源争用。

故障排查指南

本地服务无法启动
- 检查端口占用与防火墙；确认数据库与缓存服务已健康运行。
数据库迁移失败
- 查看Alembic配置与URL；确认迁移脚本语法正确；必要时回滚至上一版本。
测试异常
- 确认pytest会话级fixture已正确屏蔽定时任务；检查依赖注入覆盖是否生效。
前后端联调失败
- 核对CORS与代理配置；确认API路由与鉴权头正确传递。

章节来源

结论

通过明确的分支策略、严格的代码审查流程、规范的版本发布管理与可落地的CI/CD实践，GEO项目能够在保障交付质量的同时提升团队协作效率。建议尽快在CI平台落地上述流程，并根据实际运行情况迭代优化。

附录

快速启动命令
- docker-compose：启动所有服务并进入交互模式。
- 前端：进入frontend目录，安装依赖后启动开发服务器。
- 后端：进入backend目录，安装依赖后启动Uvicorn服务。
参考文档
- Next.js官方文档与部署指南。
- FastAPI与SQLAlchemy异步数据库实践。
- Alembic迁移最佳实践。

12 KiB Raw Blame History Unescape Escape

开发流程

目录

简介

项目结构

核心组件

架构总览

详细组件分析

Git 分支策略与工作流

代码审查流程

版本发布管理

持续集成/持续部署（CI/CD）

开发环境搭建与团队协作最佳实践

依赖关系分析

性能考虑

故障排查指南

结论

附录

12 KiB

Raw Blame History