二次开发规范

开发规范

分层职责

API路由层

• 接收前端传递的 HTTP 请求（GET/POST/PUT 等）；
• 对请求参数进行校验（如参数类型、非空校验）；
• 调用业务服务层的方法完成核心逻辑；
• 统一格式返回响应结果（成功 / 失败）。

业务服务层

• 遵循Fail Fast原则（快速失败，尽早发现并抛出异常）
• 封装所有业务逻辑，如业务规则判断、多模块调用协调；
• 调用数据库操作层完成数据存取、调用文件 / 第三方服务处理；
• 负责异常的捕获与转换，对底层异常进行业务化封装；

数据库操作层

• 保持“纯粹的数据操作”，仅负责基础的数据库 CRUD 操作（增删改查、列表查询）
• 不做业务规则校验（如是否检查资源存在、数据是否符合业务要求）

分层开发代码示例

体现业务判断在服务层、纯数据操作在数据库层的原则

### controller.py API路由层
@router.delete("/{kb_id}", response_model=SuccessResponse, summary="删除知识库")
async def delete_kb(
    kb_id: int,
    db: AsyncSession = Depends(get_db),
):
    """删除知识库"""
    await KnowledgeBaseService.delete_kb_service(db, kb_id)
    return SuccessResponse()


### service.py 业务服务层
async def delete_kb_service(db: AsyncSession, kb_id: int) -> None:
    kb = await get_kb(db, kb_id)
    if not kb:
        raise BusinessException(code=404, msg="知识库不存在")
    await delete_kb(db, kb)
  

### crud.py 数据操作层
async def get_kb(db: AsyncSession, kb_id: int) -> Optional[KnowledgeBase]:
    return await db.get(KnowledgeBase, kb_id)

async def delete_kb(db: AsyncSession, kb: KnowledgeBase) -> None:
    await db.delete(kb)
    await db.commit()

命名规范

model.py 模型层

• 类名：XxxModel格式，以Model结尾，名词单数，大驼峰命名；
• 示例：DeptModel（部门表）、MenuModel（菜单表）、KnowledgeBaseModel（知识库表）；
• 表名__tablename__：yyy_xxx格式，小写下划线，yyy为所属组件名；
• 示例：system_dept（系统模块 - 部门表）、kb_document（知识库模块 - 文档表）。

schema.py 模式层

• 格式：XxxSchema格式，以Schema结尾，大驼峰命名；
• 示例：公共模型（可选）DeptSchema、创建模型DeptCreateSchema、更新模型DeptUpdateSchema、响应模型DeptResponseSchema、查询模型DeptQuerySchema；

crud.py 数据库操作层

• 格式：以crud结尾，小写下划线命名，遵循操作_资源_crud规则；
• 示例：创建create_menu_crud、删除delete_menu_crud、更新update_menu_crud、单条查询get_menu_crud、列表查询get_menu_list_crud；

service.py 业务服务层

• 类名：XxxService格式，以Service结尾，大驼峰命名，示例DocumentService、KnowledgeBaseService；
• 方法名：封装为类方法，以service结尾，小写下划线命名，示例DocumentService.get_document_service、KnowledgeBaseService.create_kb_service；

controller.py API路由层

• URL 中使用名词表示资源（而非动词），因为 HTTP 方法已表示操作类型；
• 全小写，资源名用单数（如/document），路径参数用{id}表示唯一标识；
• 不同操作对应不同 HTTP 方法，无需在 URL 中添加/create//delete等动词；

操作	HTTP 方法	URL	说明
获取文档列表	GET	/document	支持分页、筛选参数
创建新文档	POST	/document	请求体传递 JSON 格式数据
获取单个文档	GET	/document/{id}	根据 ID 查询单条文档
全量更新文档	PUT	/document/{id}	替换文档的所有字段
部分更新文档	PATCH	/document/{id}	仅更新文档的指定字段
删除文档	DELETE	/document/{id}	根据 ID 删除指定文档