# 路由注册

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

## 文件位置

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

## 注册步骤

### 第一步：定义模块路由

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

```python
# +======================================================================
# | 模块: 岗位路由层
# | 说明: 提供岗位管理的增删改查、批量删除、状态管理等 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` 列表中追加模块：

```python
# 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,  # 新增
]
```

:::tip 注册规则
新模块只需两步：
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 工作原理

```python
# 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` 自动拼接，无需手动配置。