coding-guidelines

name	开发规范 (Coding Guidelines)
description	规范当前 Python (FastAPI + SQLAlchemy) 项目的代码开发标准，涵盖编码风格、分层架构、数据库及异常处理等。

开发规范

本 Skill 用于指导当前项目的代码开发，确保代码风格统一、结构清晰且易于维护。在协助进行代码生成、重构或修改时，请务必遵循以下规范：

1. 编码风格 (Code Style)

• PEP 8：严格遵循 PEP 8 规范。
• 类型提示 (Type Hints)：强制使用类型注解。所有的函数、方法参数及返回值必须明确指定类型，以支持静态检查和代码智能感知。
• 命名规范：
  • 包名/模块名/变量名/函数名：snake_case
  • 类名：PascalCase
  • 常量名：UPPER_SNAKE_CASE
• 代码格式化：假设项目使用了 black、ruff 或 isort，在编写代码时应保持与之相符的格式。

2. 架构设计与分层 (Architecture)

• 目录结构：
  • 业务模块目录：每个业务模块应有独立的目录
    • api：定义与外部交互的接口（如 FastAPI 路由）
      • endpoints：具体的 API 端点实现
      • dependencies.py：定义 API 层的依赖项（如service 层的依赖）
      • router.py：定义 API 路由
    • domain：核心业务逻辑和领域模型
      • models：定义数据库模型（SQLModel）
      • services：定义业务服务类，封装核心业务逻辑
      • repositories：定义数据访问层，封装数据库操作
        • implementations：具体的 Repository 实现，应继承 BaseRepositoryImpl[ModelClass, IDType], RepositoryInterface
        • interfaces：定义 Repository 接口，应继承 BaseRepository[ModelClass, IDType], ABC
      • schemas：定义 Pydantic 模型，用于数据验证和序列化

3. 数据库与 ORM (SQLAlchemy & Alembic)

• 表结构变动：所有数据库表结构的增删改，必须通过 Alembic 生成迁移文件（如 alembic revision --autogenerate），禁止直接手动修改数据库表结构。
  • versions 目录所在路径：bisheng/core/database/alembic/versions
  • 可以阅读 bisheng/core/database/alembic/README.md
• 数据库操作：所有数据库的增删改查必须通过 SQLModel 或 SQLAlchemy ORM 模型进行，止禁直接使用原生 SQL 语句。
  • 数据库会话（Session）应通过依赖注入的方式获取,或者通过装饰器（如 @db_session）进行管理，确保事务的一致性和正确的资源释放。
• 模型定义：使用SQLModel 定义数据库模型，确保与数据库表结构一致，并且支持 Pydantic 的数据验证,使用sa_column等方式定义字段属性。
  • 模型类应放在 models 模块中，且每个模型类应有明确的表名（__tablename__）和字段定义。
  • 模型字段应使用 SQLModel 的 Field 函数进行定义，明确字段类型、默认值、索引等属性。
• 查询规范：尽量使用 SQLModel 的查询接口进行数据操作，避免直接使用原生 SQL 语句。对于复杂查询，可以在 Repository 层封装成方法，并提供清晰的接口。
  • 如果有需要查询多张表的业务逻辑，尽量使用 JOIN 或子查询的方式进行，而不是在 Python 代码中进行多次查询和数据处理。
  • 对于分页查询，建议使用 SQLModel 的分页功能，或者在 Repository 层封装一个通用的分页方法，以提高代码复用性和性能。
  • 对于批量操作（如批量插入、更新），建议使用 SQLModel 的批量操作接口，以提高效率和性能。

4. 异常处理与日志 (Exception Handling & Logging)

• 分业务自定义异常：每个业务模块应定义自己的异常类，继承自一个公共的基类（如 BaseErrorCode）
  • 在 bisheng/common/errcode 目录下定义不同业务的异常文件，如 user.py、knowledge.py 等，每个文件中定义该业务相关的异常类。
  • 自定义异常类集成 BaseErrorCode，并设置Code、Msg属性，以便在 API 层统一处理和返回错误响应。
  • 在业务逻辑中，遇到错误情况时应抛出相应的自定义异常，raise UserNotFoundError()，而不是直接返回错误码或字符串。API 层应捕获这些异常，并根据异常的 Code 和 Msg 生成统一的错误响应。
• 日志记录：在关键业务流程、异常捕获点以及重要的操作步骤中，应使用 Python 的 logging或 loguru 进行日志记录，确保日志内容清晰、结构化，并包含必要的上下文信息（如用户ID、请求ID等），以便于后续的调试和问题排查。
  • 日志级别应合理使用，如 DEBUG 用于开发调试，INFO 用于正常操作记录，WARNING 用于潜在问题，ERROR 用于错误事件，CRITICAL 用于严重错误。
  • 日志记录应使用英文，保持国际化和专业性，并且日志消息应简洁明了，能够清晰地传达事件的发生和相关信息。

5. 注释与文档 (Comments & Documentation)

• 注释和文档应使用英文，以保持国际化和专业性。
• Docstrings：核心公共函数、类、复杂的业务方法必须包含文档字符串，说明其功能、参数详情和返回类型。
• 内联注释：对于反直觉的代码实现或特别复杂的逻辑，需要有注释说明“为什么”这么写，而不仅仅是“做了什么”。

在每一次开发或答疑中，请将这份开发规范作为判断代码质量和架构是否合理的评价标准。