项目开发规范

⚠️ 重要提示：所有后续 AI 接手本项目时，必须优先阅读并严格遵守此规范。

项目代码开发规范

**重要：所有后续 AI 接手本项目时，必须优先阅读并严格遵守此规范。**

>

适用范围：8080 风险分析系统、8081 爬虫管理系统、以及本项目未来所有子系统。

目录

  1. [总则](#1-总则)
  2. [Python 后端规范](#2-python-后端规范)
  3. [前端规范](#3-前端规范)
  4. [数据库规范](#4-数据库规范)
  5. [API 设计规范](#5-api-设计规范)
  6. [错误处理规范](#6-错误处理规范)
  7. [日志规范](#7-日志规范)
  8. [文件与目录组织](#8-文件与目录组织)
  9. [版本控制规范](#9-版本控制规范)
  10. [文档规范](#10-文档规范)

1. 总则

1.1 必须遵守

  • **任何修改前**，先读取相关模块的现有代码，确保风格一致。
  • **禁止**在没有理解现有代码结构的情况下大规模重写。
  • **禁止**将敏感信息（密码、密钥、Token）硬编码在代码中，使用环境变量或配置文件。
  • **禁止**在代码中遗留调试用的 print()、console.log()、debugger 等语句（生产环境）。

1.2 代码审查清单

提交代码前必须自检：

  • [ ] 代码是否能正常运行？
  • [ ] 是否处理了异常情况？
  • [ ] 是否有适当的注释和文档字符串？
  • [ ] 变量/函数命名是否清晰？
  • [ ] 是否引入了重复代码？
  • [ ] 数据库操作是否有连接关闭保证？

2. Python 后端规范

2.1 命名规范

2.2 类型提示（强制）

类型规范示例
模块/包`snake_case`，小写`data_service.py`
类`PascalCase``CrawlerConfig`, `QueueManager`
函数/方法`snake_case`，动词开头`get_author_stats()`, `sync_data()`
变量`snake_case``author_id`, `content_count`
常量`UPPER_SNAKE_CASE``MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE`
私有函数前缀 `_``_get_mysql_conn()`
私有变量前缀 `_``_crawler_process`

**所有函数必须添加类型提示**，包括参数和返回值：


# ✅ 正确
async def get_author_stats(platform: str, user_id: str) -> Dict[str, Any]:
    """获取作者关联数据统计。"""
    pass

# ❌ 错误
def get_author_stats(platform, user_id):
    pass

常用类型导入：


from typing import Optional, Dict, Any, List, Tuple, Union

2.3 文档字符串（Docstring）

**所有公共函数必须有文档字符串**，说明：

  • 函数功能（一句话）
  • 参数说明
  • 返回值说明
  • 异常说明（如有）

async def delete_author(platform: str, user_id: str) -> Dict[str, Any]:
    """删除作者及其关联数据（级联删除）。
    
    Args:
        platform: 平台代码，如 'dy'/'xhs'
        user_id: 作者ID
    
    Returns:
        {'success': bool, 'message': str} 或 {'success': False, 'error': str}
    
    Note:
        只操作本系统的数据库，不修改其他系统数据。
    """

2.4 函数长度限制

  • **单个函数不超过 80 行**（不含注释和空行）。
  • 超过 80 行的函数必须拆分为多个子函数。

2.5 代码格式化

使用 black 格式化 Python 代码（行宽 100）：


black --line-length 100 .

使用 ruff 做静态检查：


ruff check .

2.6 导入排序

按以下顺序分组，组间空一行：


# 1. 标准库
import os
import json
from datetime import datetime
from typing import Optional, Dict, Any

# 2. 第三方库
import pymysql
from fastapi import FastAPI

# 3. 本项目模块
from ..db.connection import fetch_one, fetch_all
from .utils import parse_count

3. 前端规范

3.1 命名规范

3.2 代码组织


// ✅ 正确：函数有注释说明
/**
 * 加载作者列表并渲染到表格
 * @param {number} page - 当前页码
 * @param {number} pageSize - 每页数量
 */
async function loadAuthors(page = 1, pageSize = 20) {
    // 实现...
}

// ❌ 错误：无注释、无参数说明
function load() { ... }

3.3 事件处理

类型规范示例
HTML ID`camelCase` 或 `kebab-case``authorsTable`, `authors-table`
CSS 类`kebab-case``btn-primary`, `card-value`
JavaScript 函数`camelCase`，动词开头`loadAuthors()`, `handleClick()`
JavaScript 变量`camelCase``authorsPage`, `totalCount`
全局变量前缀 `g` 或明确命名空间`gCurrentUser`
  • 使用 onclick 等内联事件时，保持简洁，复杂逻辑提取为函数。
  • 避免在 HTML 中写复杂的 JavaScript 表达式。

4. 数据库规范

4.1 SQL 编写规范

  • **禁止字符串拼接 SQL**，必须使用参数化查询：

# ✅ 正确
cur.execute("SELECT * FROM authors WHERE platform = %s", (platform,))

# ❌ 错误（SQL 注入风险）
cur.execute(f"SELECT * FROM authors WHERE platform = '{platform}'")
  • **表名/字段名用反引号包裹**：` table_name `
  • **复杂查询用多行字符串**，保持可读性

4.2 连接管理

**必须确保连接关闭**，使用 try...finally 或上下文管理器：


def query_data():
    conn = get_conn()
    try:
        with conn.cursor() as cur:
            cur.execute("SELECT ...")
            return cur.fetchall()
    finally:
        conn.close()  # 必须关闭

4.3 数据库设计

  • **表名**：snake_case，复数形式（如 authors, contents）
  • **字段名**：snake_case，避免 SQL 关键字（如 desc → description）
  • **主键**：id 自增整数，或业务 xxx_id + dedup_key
  • **时间字段**：created_at, updated_at, first_synced_at, last_synced_at
  • **索引**：为经常查询的字段建立索引，索引名 idx_表名_字段名

4.4 数据同步规范

  • **8080 只读 8081 数据库**，不直接修改。
  • **8081 不访问 8080 数据库**。
  • 数据同步通过 ETL 脚本完成，记录同步日志到 sync_tasks 表。

5. API 设计规范

5.1 URL 设计

5.2 响应格式

规范示例
使用名词复数`/api/authors`, `/api/contents`
资源层级用 `/``/api/authors/douyin/12345/stats`
过滤用查询参数`/api/authors?platform=dy&page=1`
动作不用动词❌ `/api/authors/delete`，✅ `DELETE /api/authors/{id}`

统一响应结构：


{
    "success": true,
    "data": { ... },
    "message": "操作成功"
}

或错误时：


{
    "success": false,
    "error": "具体错误信息",
    "code": "ERROR_CODE"
}

列表查询响应：


{
    "total": 100,
    "page": 1,
    "page_size": 20,
    "items": [ ... ]
}

5.3 HTTP 状态码

6. 错误处理规范

6.1 Python 异常处理


# ✅ 正确：捕获具体异常，记录日志
import logging
logger = logging.getLogger(__name__)

try:
    result = await fetch_one("SELECT ...")
except pymysql.Error as e:
    logger.error(f"数据库查询失败: {e}", exc_info=True)
    return {"success": False, "error": f"数据库错误: {e}"}
except Exception as e:
    logger.error(f"未知错误: {e}", exc_info=True)
    return {"success": False, "error": "系统内部错误"}

6.2 前端错误处理


// ✅ 正确：统一错误处理
async function apiGet(url) {
    try {
        const res = await fetch(url);
        if (!res.ok) {
            throw new Error(`HTTP ${res.status}`);
        }
        return await res.json();
    } catch (e) {
        console.error('API 请求失败:', e);
        alert('请求失败: ' + e.message);
        throw e;  // 继续抛出，让调用方处理
    }
}

7. 日志规范

7.1 Python 日志


import logging

logger = logging.getLogger(__name__)

# 记录信息
logger.info(f"同步完成: 新增 {inserted} 条, 更新 {updated} 条")

# 记录警告
logger.warning(f"作者 {author_id} 不存在，跳过")

# 记录错误（必须带 exc_info）
logger.error(f"同步失败: {e}", exc_info=True)

7.2 日志级别使用

8. 文件与目录组织

8.1 项目结构


risk-crawler/
├── web_ui/                    # 8080 风险分析系统
│   ├── backend/               # 后端
│   │   ├── app/
│   │   │   ├── api/           # API 路由
│   │   │   ├── db/            # 数据库连接
│   │   │   ├── services/      # 业务逻辑
│   │   │   └── monitoring/    # 监控模块
│   │   ├── scripts/           # 工具脚本
│   │   └── main.py            # 入口
│   ├── frontend/              # 前端页面
│   └── README.md              # 系统文档
│
├── crawler_webui/             # 8081 爬虫管理系统
│   ├── main.py                # 后端入口
│   ├── static/                # 前端静态文件
│   └── README.md              # 系统文档
│
├── vendor/                    # 第三方库
│   └── MediaCrawlerPro-Python/
│
├── CODE_OF_CONDUCT.md         # 本规范文件（项目根目录）
└── README.md                  # 项目总览

8.2 单文件行数限制

场景状态码
成功200
创建成功201
参数错误400
未认证401
权限不足403
资源不存在404
服务器错误500
级别使用场景
DEBUG调试信息，开发时使用
INFO正常业务流程记录
WARNING非致命异常，可继续执行
ERROR致命错误，需要处理
CRITICAL系统级错误，需要立即响应
  • Python 模块文件：**不超过 500 行**。超过必须拆分。
  • HTML/JS 文件：**不超过 1000 行**。超过必须拆分或模块化。

9. 版本控制规范

9.1 Git 提交信息

格式：[类型] 简短描述

9.2 分支管理

类型说明示例
`feat`新功能`[feat] 添加作者批量删除功能`
`fix`修复 Bug`[fix] 修复队列操作按钮缺失问题`
`docs`文档更新`[docs] 更新数据库配置说明`
`refactor`重构`[refactor] 拆分 data.py 为多个模块`
`perf`性能优化`[perf] 优化评论同步批量处理`
`chore`杂项`[chore] 更新依赖版本`
  • main：主分支，稳定版本
  • develop：开发分支
  • feature/xxx：功能分支
  • hotfix/xxx：紧急修复

10. 文档规范

10.1 必须存在的文档

10.2 文档更新要求

文档位置内容
系统 README每个子系统根目录系统定位、技术栈、启动方式、配置
API 文档`docs/api.md` 或注释接口列表、参数、返回值
数据库文档`docs/db.md` 或 README 中表结构、字段说明、关系图
本规范`CODE_OF_CONDUCT.md`代码开发规范
  • **修改代码时同步更新相关文档**
  • **新增 API 时必须补充文档**
  • **数据库表结构变更时更新数据字典**

附：规范执行检查清单

新增/修改代码前，确认：

  • [ ] 命名符合规范
  • [ ] 添加了类型提示
  • [ ] 添加了文档字符串
  • [ ] 处理了异常情况
  • [ ] 数据库连接正确关闭
  • [ ] 没有硬编码敏感信息
  • [ ] 函数长度不超过 80 行
  • [ ] 通过了 black 格式化
  • [ ] 更新了相关文档
**最后更新**: 2026-07-11

>

**执行优先级**: 🔴 **最高** — 所有 AI 接手本项目时必须首先阅读并遵守。