zk
105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
---
|
||
inclusion: manual
|
||
---
|
||
|
||
# 代码开发风格文档
|
||
|
||
本项目为 Python 3.12 纯后台定时任务服务，基于 asyncio + SQLAlchemy + APScheduler，应用主目录为 `app/`。
|
||
|
||
## 项目结构
|
||
|
||
- `app/config/` — 配置层：Pydantic Settings 统一配置
|
||
- `app/core/` — 核心基础设施：双数据源连接、日志
|
||
- `app/ai/` — AI 能力层：LLM 模型枚举、场景配置、Prompt 模板
|
||
- `app/models/` — ORM 模型层：分 pg/ 和 mysql/ 两个子包
|
||
- `app/services/` — 业务逻辑层：清洗、补充、恢复、下架等异步服务
|
||
- `app/scheduler/` — 调度层：APScheduler 定时任务注册
|
||
|
||
## 命名约定
|
||
|
||
### 文件命名
|
||
- 全部小写，下划线分隔，如 `job_clean_service.py`、`dict_cache_service.py`
|
||
- ORM 模型文件与表名对应（去掉 `bg_` 或 `app_` 前缀），如 `job.py` 对应 `bg_job`
|
||
|
||
### 类命名
|
||
- ORM 模型用 PascalCase 业务名，无后缀，如 `Job`、`Company`、`AppJobData`
|
||
- 字典缓存用 `DictCacheService`
|
||
- 枚举类以大写命名，如 `LLM`
|
||
- 场景配置类以 `Model` 结尾，如 `JobCleanModel`、`CompanyCleanModel`
|
||
|
||
### 变量与函数命名
|
||
- 函数和变量使用 snake_case，如 `run_job_clean`、`data_id`
|
||
- 私有函数以单下划线开头，如 `_do_clean`、`_build_user_message`
|
||
- 常量使用全大写下划线，如 `JOB_STRUCTURE_SYSTEM`
|
||
- 全局单例小写，如 `dict_cache`、`_id_gen`
|
||
|
||
## 类型注解
|
||
|
||
- 所有函数参数和返回值必须有类型注解
|
||
- ORM 模型字段使用 `Mapped[T]` + `mapped_column()` 声明
|
||
- 可选字段使用 `Optional[T]` 或 `T | None`
|
||
- 集合类型使用 `list[T]`、`dict[K, V]`（Python 3.12 内置泛型）
|
||
|
||
## 注释规范
|
||
|
||
- 模块级注释使用文件顶部的 docstring，说明模块用途
|
||
- 函数注释使用 docstring，简洁描述功能
|
||
- 复杂逻辑用行内注释 `#` 说明
|
||
- ORM 模型字段通过 `comment` 参数说明含义
|
||
|
||
## 数据库使用规范
|
||
|
||
### 双数据源
|
||
- PostgreSQL 会话通过 `PgSession()` 获取，用于 `app_job_data` 表操作
|
||
- MySQL 会话通过 `MysqlSession()` 获取，用于业务表操作
|
||
- 每次操作用 `async with XxxSession() as session` 获取会话，手动 `await session.commit()`
|
||
|
||
### SQL 风格
|
||
- 简单操作使用 `sqlalchemy.text()` 原生 SQL，保持直观
|
||
- 批量插入使用 `insert(Model).values(...)` 或 `insert(Model), [dict...]`
|
||
- 锁定使用 `FOR UPDATE SKIP LOCKED`（PG）防阻塞
|
||
|
||
### 不做分布式事务
|
||
- PG 和 MySQL 独立操作，不跨库事务
|
||
- 失败靠僵尸恢复机制重试
|
||
|
||
## 异步规范
|
||
|
||
- 所有数据库操作、AI 调用使用 `async/await`
|
||
- 并发控制使用 `asyncio.Semaphore`
|
||
- 互斥操作使用 `asyncio.Lock()`（如公司查找或创建）
|
||
- 批量任务使用 `asyncio.gather(*tasks, return_exceptions=True)`
|
||
|
||
## AI 调用规范
|
||
|
||
- 业务代码从 `app.ai.model_config` 引用场景配置类，不直接使用 `LLM` 枚举
|
||
- AI 调用统一通过 `app.services.ai_tool.ai_chat_json()` 封装（异步调用 + JSON 清洗 + 解析）
|
||
- AI 调用失败不影响主流程（第二次/第三次 AI 调用独立 try-catch）
|
||
- 修改模型或参数只需改 `model_config.py`
|
||
|
||
## 日志规范
|
||
|
||
- 使用 `from app.core.logger import log`
|
||
- 批次任务：记录锁定数量和完成汇总
|
||
- 单条处理：记录关键结果（入库成功/丢弃/跳过），格式 `[id=xxx] 描述`
|
||
- 异常：`log.error` 记录异常详情
|
||
- 非关键失败：`log.warning` 记录但不中断
|
||
|
||
## 配置规范
|
||
|
||
- 所有可调参数放在 `settings.py`，通过 `.env` 文件覆盖
|
||
- 运行时参数（batch_size、concurrency、interval、expire_days）必须可配置
|
||
- 数据库密码通过 `urllib.parse.quote` 编码后拼入 URL
|
||
|
||
## 代码格式规范
|
||
|
||
### 紧凑风格
|
||
- 避免过度换行，保持代码紧凑易读
|
||
- f-string 拼接优先写在一行
|
||
- 方法参数列表较多时，可适当换行但保持紧凑
|
||
|
||
### 模块组织
|
||
- 每个 service 文件对外暴露一个 `run_xxx()` 异步函数作为入口
|
||
- 内部逻辑拆分为 `_xxx` 私有函数
|
||
- import 按标准库 → 第三方库 → 项目内部 顺序排列
|