fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/开发指南/代码规范.md

15 KiB
Raw Blame History

代码规范

**本文档引用的文件** - [backend/requirements.txt](file://backend/requirements.txt) - [backend/alembic.ini](file://backend/alembic.ini) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/app/api/auth.py](file://backend/app/api/auth.py) - [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py) - [backend/app/models/user.py](file://backend/app/models/user.py) - [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py) - [tests/test_auth.py](file://tests/test_auth.py) - [frontend/package.json](file://frontend/package.json) - [.eslintrc.json](file://frontend/.eslintrc.json) - [frontend/tsconfig.json](file://frontend/tsconfig.json) - [frontend/app/layout.tsx](file://frontend/app/layout.tsx) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/components/ui/button.tsx](file://frontend/components/ui/button.tsx) - [frontend/types/next-auth.d.ts](file://frontend/types/next-auth.d.ts)

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

引言

本文件为 GEO 项目的统一代码规范文档，覆盖后端 Python 与前端 TypeScript/Next.js 的风格与实践，明确命名约定、导入顺序、注释规范、类型与接口设计、模块组织、错误处理模式以及前后端一致性要求，并提供可操作的自动化检查工具配置与使用方法。文档同时给出“正确/错误”示例的路径指引，便于团队在开发过程中快速对照与改进。

项目结构

  • 后端采用 FastAPI + SQLAlchemy 2.x + Pydantic v2，使用异步数据库会话与依赖注入，模块按功能分层：API 路由、服务层、模型与模式（schemas）、工作流与调度。
  • 前端采用 Next.js App Router + TypeScript + TailwindCSS，UI 组件基于 Radix UI 与 class-variance-authority，类型扩展用于 NextAuth。
graph TB
subgraph "后端"
MAIN["app/main.py<br/>应用入口与路由挂载"]
AUTH_API["app/api/auth.py<br/>认证路由"]
SCHEMA_AUTH["app/schemas/auth.py<br/>认证模式"]
MODEL_USER["app/models/user.py<br/>用户模型"]
WORKER["app/workers/citation_engine.py<br/>引用检测引擎"]
CONFIG["app/config.py<br/>配置读取"]
end
subgraph "前端"
LAYOUT["app/layout.tsx<br/>根布局与元数据"]
API_TS["lib/api.ts<br/>API 封装"]
BTN["components/ui/button.tsx<br/>按钮组件"]
TYPES["types/next-auth.d.ts<br/>NextAuth 类型扩展"]
end
MAIN --> AUTH_API
AUTH_API --> SCHEMA_AUTH
AUTH_API --> MODEL_USER
MAIN --> WORKER
MAIN --> CONFIG
LAYOUT --> API_TS
API_TS --> AUTH_API
BTN --> LAYOUT
TYPES --> LAYOUT

图示来源

章节来源

核心组件

  • 应用入口与中间件：统一设置 CORS、健康检查端点、路由挂载与生命周期管理。
  • 认证模块：注册、登录、当前用户信息获取，配合 Pydantic 模式与数据库模型。
  • 引擎与工作流：引用检测引擎封装品牌匹配、竞争品牌识别与多平台适配器调用。
  • 前端 API 封装：统一鉴权头、错误处理与资源访问；UI 组件通过变体系统实现一致风格。
  • 类型与扩展：NextAuth 类型扩展确保会话与 JWT 字段的类型安全。

章节来源

架构总览

后端通过 FastAPI 提供 REST 接口，前端通过 Next.js App Router 渲染页面并通过封装的 API 客户端访问后端。测试覆盖认证流程与错误场景，确保行为符合预期。

sequenceDiagram
participant FE as "前端页面"
participant API as "lib/api.ts"
participant BE as "FastAPI 路由"
participant SVC as "服务/模型"
FE->>API : "调用认证/查询/报告接口"
API->>BE : "携带 Authorization 头发起请求"
BE->>SVC : "依赖注入与业务处理"
SVC-->>BE : "返回响应或异常"
BE-->>API : "标准化响应"
API-->>FE : "解析并渲染结果"

图示来源

详细组件分析

Python 后端代码规范

  • 语言与版本：使用 Python 3.x，推荐 3.10+。
  • 依赖管理：通过 requirements.txt 管理生产与测试依赖。
  • 代码风格与静态检查：Alembic 配置中预留了格式化与检查钩子（如 black/ruff），建议在本地与 CI 中启用以保持一致性。
  • 命名约定
    • 模块与包：小写、下划线分隔（如 app/api/auth.py）。
    • 类：大驼峰（如 User、CitationEngine）。
    • 函数与变量：小写加下划线（如 register_user、execute_query）。
    • 常量：全大写加下划线（如 DATABASE_URL）。
  • 导入顺序
    • 标准库 → 第三方库 → 项目内相对导入（遵循相对导入与绝对导入的一致性）。
    • FastAPI 路由模块中，先导入标准库与第三方，再导入项目内模块。
  • 注释规范
    • 模块级 docstring：简述模块职责。
    • 类与函数：使用三引号 docstring，描述参数、返回值与异常。
    • 关键逻辑处添加行内注释，解释复杂算法或边界条件。
  • 错误处理
    • 使用 HTTPException 抛出语义化错误，避免泄露内部细节。
    • 服务层捕获业务异常并转换为 HTTP 状态码。
  • 类型与数据模型
    • 使用 Pydantic v2 BaseModel 定义输入输出模式，配合 EmailStr、Field 等约束。
    • SQLAlchemy ORM 模型使用 mapped_column、mapped_alias 等现代语法。
  • 并发与异步
    • 使用 AsyncSession 与 async/await，避免阻塞操作。
  • 示例路径

章节来源

TypeScript/JavaScript 前端代码规范

  • 语言与编译选项：严格模式、ESNext 模块解析、Bundler 解析、JSX 保留。
  • 命名约定
    • 文件：小写加连字符（如 api.ts），组件使用 PascalCase（如 Button）。
    • 变量与函数：小驼峰（如 fetchWithAuth）。
    • 类型：接口与类型别名使用大驼峰（如 ButtonProps）。
  • 导入顺序
    • 先标准库与第三方，再内部路径别名（如 @/*）。
  • 注释规范
    • 函数与接口：使用 JSDoc 风格注释，说明参数、返回值与异常。
    • 复杂逻辑处补充行内注释。
  • 类型定义与接口设计
    • 使用 TypeScript 接口与联合类型表达数据结构。
    • NextAuth 类型扩展确保会话与 JWT 字段类型安全。
  • 模块组织
    • API 客户端集中于 lib/api.ts，按领域拆分子模块。
    • UI 组件位于 components/ui，通过变体系统统一风格。
  • 错误处理模式
    • 统一的 fetchWithAuth 封装：校验响应状态、提取错误详情并抛出错误。
    • 页面侧通过 try/catch 或 Promise.catch 捕获并提示。
  • 示例路径

章节来源

前后端一致性要求

  • 接口契约
    • 请求与响应字段命名保持一致（如 email、password、access_token）。
    • 错误响应结构统一（包含 detail 字段）。
  • 鉴权与头部
    • 前端统一在 Authorization 头中携带 Bearer Token。
    • 后端路由对未认证请求返回 401。
  • 资源路径
    • 前端 API 基础地址通过环境变量控制，与后端路由前缀保持一致。
  • 示例路径

章节来源

自动化代码检查工具配置与使用

  • 后端
    • Alembic 配置预留了 post_write_hooks，可集成 black 与 ruff 进行格式化与检查。
    • 建议在本地与 CI 中启用：格式化（black）与静态检查（ruff/flake8/pylint）。
    • 依赖声明参考 requirements.txt，确保工具链可用。
  • 前端
    • ESLint 通过 .eslintrc.json 扩展 next/core-web-vitals 与 next/typescript。
    • 建议在本地与 CI 中运行 lint 脚本，修复问题后再提交。
    • TS 编译配置启用 strict 模式，提升类型安全性。
  • 示例路径

章节来源

依赖分析

  • 后端依赖
    • Web 框架：FastAPI、Uvicorn
    • 数据库：SQLAlchemy 2.x、Asyncpg、Alembic
    • 数据验证与配置：Pydantic v2、Pydantic-Settings、email-validator
    • 认证与安全：python-jose、passlib、multipart
    • 缓存与任务调度：Redis、APScheduler
    • 浏览器自动化：Playwright
    • HTTP 客户端与工具：HTTPX、python-dotenv
    • 测试：pytest、pytest-asyncio、aiosqlite
  • 前端依赖
    • 运行时：Next.js、React、NextAuth
    • UI：Radix UI、Recharts、TailwindCSS
    • 开发工具：ESLint、TypeScript、PostCSS、TailwindCSS
graph LR
subgraph "后端"
FASTAPI["FastAPI"]
SQLA["SQLAlchemy 2.x"]
PYD["Pydantic v2"]
REDIS["Redis"]
APS["APScheduler"]
PW["Playwright"]
HTTPX["HTTPX"]
PYTEST["pytest"]
end
subgraph "前端"
NEXT["Next.js"]
REACT["React"]
NA["NextAuth"]
RUI["Radix UI"]
REC["Recharts"]
TSC["TypeScript"]
ESL["ESLint"]
end
FASTAPI --> SQLA
FASTAPI --> PYD
FASTAPI --> REDIS
FASTAPI --> APS
FASTAPI --> HTTPX
NEXT --> REACT
NEXT --> NA
NEXT --> RUI
NEXT --> REC
NEXT --> TSC
NEXT --> ESL

图示来源

章节来源

性能考虑

  • 异步优先：后端使用 AsyncSession 与异步 I/O，避免阻塞事件循环。
  • 任务调度：APScheduler 合理设置频率与并发，避免重复任务与资源争用。
  • 缓存策略：Redis 用于热点数据缓存与会话存储，减少数据库压力。
  • 前端渲染：Next.js App Router 与静态生成/预渲染结合，降低首屏延迟。
  • 网络请求：统一的 API 客户端封装，避免重复请求与无谓重试。

故障排查指南

  • 认证失败
    • 检查前端是否正确传递 Authorization 头。
    • 检查后端路由是否正确处理 401 场景。
    • 参考测试用例断言与错误消息。
  • 数据库连接
    • 确认 DATABASE_URL 与容器网络可达。
    • 检查 Alembic 迁移是否成功。
  • 任务执行异常
    • 查看日志与 QueryTask 状态更新，定位具体平台适配器问题。
  • 前端类型错误
    • 启用 TS 严格模式，修复类型不匹配。
    • 使用 ESLint 规则约束代码质量。

章节来源

结论

本规范明确了 GEO 项目在 Python 与 TypeScript 生态下的风格与实践，强调一致性、可维护性与可测试性。建议在本地与 CI 中强制执行格式化与静态检查，持续完善测试覆盖，确保前后端契约稳定与类型安全。

附录