路由注册

概述

路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。

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

文件位置

src/routes/v1.py

注册步骤

第一步：导入 Blueprint

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

from src.modules.system.position.router import position_blue

第二步：挂载 Blueprint

在 BLUEPRINTS 列表中添加：

BLUEPRINTS = [
    # ... 其他 Blueprint
    position_blue,
]

完整上下文

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

from flask import Blueprint

from src.modules.system.position.router import position_blue
from src.modules.system.level.router import level_blue
from src.modules.system.dept.router import dept_blue
# ... 其他模块导入

# 全部业务蓝图（按领域分组排序）
BLUEPRINTS = [
    position_blue,
    level_blue,
    dept_blue,
    # ... 其他模块注册
]


def register_v1(app):
    """
    注册 API v1 路由（所有业务蓝图挂载到 /api/v1）。

    Args:
        app: Flask 应用实例
    """
    v1 = Blueprint('v1', __name__, url_prefix='/api/v1')
    for blue in BLUEPRINTS:
        v1.register_blueprint(blue)
    app.register_blueprint(v1)
    return app

最终 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

Blueprint 定义示例

在模块的 router.py 文件中定义 Blueprint：

# src/modules/system/position/router.py
from flask import Blueprint, request

from src.middleware import check_demo, operation_log
from src.core.permission import check_permission
from src.modules.system.position import service as position
from src.common.utils.request import parse_request_body
from src.core import response as R

position_blue = Blueprint('position', __name__, url_prefix='/position')


@position_blue.route('/page', methods=["GET"])
@check_permission("sys:position:page")
@operation_log("岗位管理", "查询")
def page():
    """查询岗位分页数据"""
    return R.ok(data=position.get_position_page(request.args))


@position_blue.route('/add', methods=["POST"])
@check_permission("sys:position:add")
@check_demo
@operation_log("岗位管理", "新增")
def add():
    """添加岗位"""
    json_data, err = parse_request_body()
    if err:
        return R.failed(msg=err)
    position.add_position(json_data)
    return R.ok(msg="添加成功")

开发要点

1. 只需两步：一行导入，一行添加到 BLUEPRINTS 列表
2. prefix 与模块目录名保持一致：便于代码导航
3. 所有业务蓝图都挂在 v1 路由组下：自动享受 login_required 认证保护
4. 使用 check_permission 装饰器：实现 RBAC 权限控制

总结

路由注册在 src/routes/v1.py 中统一管理，BLUEPRINTS 列表包含所有业务模块的 Blueprint。所有业务蓝图挂在 v1 路由组下，自动享受 login_required 认证保护。使用 check_permission 装饰器实现 RBAC 权限控制。