路由注册

路由注册是将模块的 Endpoint 挂载到应用的过程。所有模块的路由在 src/api/v1/router.py 中统一注册。

文件位置

src/api/v1/router.py

注册步骤

第一步：导入路由

在 router.py 文件顶部的导入区域添加：

from api.v1.endpoints.position import router as position_router

第二步：挂载路由

在 register_router() 函数中添加：

v1.include_router(position_router, prefix="/position", tags=["岗位管理"])

参数	说明
`position_router`	Endpoint 文件中创建的 `APIRouter` 实例
`prefix="/position"`	路由前缀，最终路径为 `/api/v1/position/xxx`
`tags=["岗位管理"]`	Swagger 文档中的分组标签

完整上下文

# router.py 中的路由注册（简化示例）

from api.v1.endpoints.position import router as position_router
from api.v1.endpoints.level import router as level_router
from api.v1.endpoints.dept import router as dept_router
# ... 其他模块导入

def register_router(app):
    # 认证相关路由（免登录）
    app.include_router(auth_router, prefix="/api", tags=["认证管理"])

    # 业务模块路由（需登录）
    v1.include_router(position_router, prefix="/position", tags=["岗位管理"])
    v1.include_router(level_router, prefix="/level", tags=["职级管理"])
    v1.include_router(dept_router, prefix="/dept", tags=["部门管理"])
    # ... 其他模块注册

    # v1 路由组挂载到应用，带 login_required 中间件
    app.include_router(v1, prefix="/api/v1")

最终 API 路径

注册后，Position 模块的接口路径为：

方法	路径	说明
GET	`/api/v1/position/page`	分页查询
GET	`/api/v1/position/detail/{id}`	详情查询
GET	`/api/v1/position/list`	列表查询
POST	`/api/v1/position/add`	新增
PUT	`/api/v1/position/update`	更新
DELETE	`/api/v1/position/delete/{id}`	单条删除
DELETE	`/api/v1/position/batchDelete`	批量删除
PUT	`/api/v1/position/status`	状态变更

prefix 命名规范

规则	示例
使用小写英文	`/position` 而非 `/Position`
使用单数形式	`/position` 而非 `/positions`
多单词用驼峰或短横线	`/jobLog` 或 `/job-log`
与模块目录名一致	`modules/system/position/` → `/position`

开发要点

只需两行代码：一行导入，一行注册
prefix 与模块目录名保持一致：便于代码导航
tags 使用中文：方便在 Swagger 文档中识别
所有业务路由都挂在 v1 路由组下：自动享受 login_required 认证保护

总结

路由注册在 src/api/v1/router.py 中统一管理，prefix 与模块目录名保持一致，tags 使用中文方便 Swagger 识别。所有业务路由挂在 v1 路由组下，自动享受 login_required 认证保护。

2.9 KiB Raw Blame History