路由注册

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

文件位置

src/api/v1/router.py
src/api/v1/{module}.py    # 每个模块的路由定义

注册步骤

第一步：定义模块路由

在 src/api/v1/position.py 中定义 routes 列表：

# +======================================================================
# | 模块: 岗位路由层
# | 说明: 提供岗位管理的增删改查、批量删除、状态管理等 API 接口
# +======================================================================
"""岗位相关路由。"""

from modules.position.handlers import (
    PositionAddHandler, PositionBatchDeleteHandler, PositionDeleteHandler,
    PositionDetailHandler, PositionGetListHandler, PositionPageHandler,
    PositionStatusHandler, PositionUpdateHandler,
)

routes = [
    # 查询岗位分页数据
    (r"/position/page", PositionPageHandler),
    # 查询岗位详情
    (r"/position/detail/(\d+)", PositionDetailHandler),
    # 获取岗位下拉列表
    (r"/position/getPositionList", PositionGetListHandler),
    # 添加岗位
    (r"/position/add", PositionAddHandler),
    # 更新岗位
    (r"/position/update", PositionUpdateHandler),
    # 删除岗位
    (r"/position/delete/(\d+)", PositionDeleteHandler),
    # 设置岗位状态
    (r"/position/status", PositionStatusHandler),
    # 批量删除岗位
    (r"/position/batchDelete", PositionBatchDeleteHandler),
]

第二步：在 router.py 中注册

在 src/api/v1/router.py 的 _RESOURCE_MODULES 列表中追加模块：

# src/api/v1/router.py
from api.v1 import (auth, index, upload, user,
                    user_role, role, role_menu, menu,
                    dept, dict, dict_item, config,
                    config_item, level, position, city,
                    notice, link, category, article,
                    param, file_template, job, generator,
                    operation_log, login_log, job_log, example)

from api.v1 import position  # 新增

_RESOURCE_MODULES = [
    auth, index, upload, user,
    # ... 已有模块 ...
    position,  # 新增
]

注册规则

新模块只需两步：

1. 在 src/api/v1/ 下创建路由文件，定义 routes 列表
2. 在 router.py 的 _RESOURCE_MODULES 中追加模块导入

路由前缀 /api/v1 由 build_routes() 自动拼接，无需手动添加。

最终 API 路径

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

方法	路径	说明
GET	/api/v1/position/page	分页查询
GET	/api/v1/position/detail/(\d+)	详情查询
GET	/api/v1/position/getPositionList	下拉列表
POST	/api/v1/position/add	新增
PUT	/api/v1/position/update	更新
DELETE	/api/v1/position/delete/(\d+)	单条删除
POST	/api/v1/position/batchDelete	批量删除
PUT	/api/v1/position/status	状态变更

URL 命名规范

规则	示例
使用小写英文	/position 而非 /Position
使用单数形式	/position 而非 /positions
多单词用驼峰	/fileTemplate 或 /file-template
路径参数用正则	(\d+) 匹配数字 ID

build_routes 工作原理

# src/api/v1/router.py
V1_PREFIX = "/api/v1"

def build_routes() -> list:
    """构建全部路由（含 /api/v1 前缀与健康检查）。"""
    routes = []
    for module in _RESOURCE_MODULES:
        routes.extend([(V1_PREFIX + path, handler) for path, handler in module.routes])
    routes.append((V1_PREFIX + "/health", HealthHandler))
    return routes

build_routes() 遍历所有模块的 routes 列表，为每条路由拼接 /api/v1 前缀，最后追加健康检查端点。

总结

路由注册采用声明式模式：每个模块在 src/api/v1/{module}.py 中定义 routes 列表，在 router.py 的 _RESOURCE_MODULES 中追加导入即可。路由前缀 /api/v1 自动拼接，无需手动配置。