帮助文档
{{userInfo.nickname}}
 用户设置 退出登录
  • {{item.name}}

{{wikiTitle}}

路由添加说明

CRMEB多店系统 - 路由添加说明

一、概述

CRMEB多店系统基于ThinkPHP 6.0的路由机制，采用分组路由管理方式，将不同模块的路由分离到独立的路由文件中。本文档详细说明如何在各个模块中添加新路由。

二、路由文件结构

2.1 路由文件位置

route/
├── admin.php      # 平台后台管理路由
├── api.php        # 用户端API路由
├── store.php      # 门店端路由
├── supplier.php   # 供应商端路由
├── cashier.php    # 收银台路由
├── kefu.php       # 客服系统路由
├── erp.php        # ERP系统路由
├── out.php        # 对外接口路由
└── zroute.php     # 其他路由配置

2.2 路由前缀对应关系

路由文件 URL前缀 控制器前缀 说明
admin.php /adminapi admin.v1 平台管理后台
api.php /api api.v1/v2 用户端接口
store.php /storeapi store 门店管理后台
supplier.php /supplierapi supplier 供应商后台
cashier.php /cashierapi cashier 收银台系统

三、路由定义语法

3.1 基本路由定义

use think\facade\Route;

// GET请求
Route::get('路径', '控制器/方法')->name('路由名称')->option(['real_name' => '路由说明']);

// POST请求
Route::post('路径', '控制器/方法')->name('路由名称')->option(['real_name' => '路由说明']);

// PUT请求
Route::put('路径', '控制器/方法')->name('路由名称')->option(['real_name' => '路由说明']);

// DELETE请求
Route::delete('路径', '控制器/方法')->name('路由名称')->option(['real_name' => '路由说明']);

// 任意请求
Route::any('路径', '控制器/方法');

3.2 带参数路由

// 必选参数
Route::get('product/:id', 'Product/detail');

// 可选参数（使用中括号）
Route::get('product/detail/:id/[:type]', 'Product/detail');

// 多个参数
Route::get('order/:order_id/item/:item_id', 'Order/itemDetail');

3.3 路由分组

Route::group('分组名', function () {
    Route::get('路径1', '控制器/方法1');
    Route::post('路径2', '控制器/方法2');
})->middleware([中间件数组])->prefix('控制器前缀.');

3.4 资源路由

// 自动生成 RESTful 风格的CRUD路由
Route::resource('user', 'user.User')->option(['real_name' => [
    'index'  => '获取用户列表',
    'read'   => '获取用户详情',
    'create' => '获取创建用户表单',
    'save'   => '保存用户',
    'edit'   => '获取修改用户表单',
    'update' => '修改用户',
    'delete' => '删除用户'
]]);

// 排除某些方法
Route::resource('user', 'user.User')->except(['create', 'edit']);
// 只包含某些方法
Route::resource('user', 'user.User')->only(['index', 'read']);

四、平台后台添加路由 (adminapi)

4.1 路由文件位置

route/admin.php

4.2 路由结构说明

Route::group('adminapi', function () {

    // 1. 无需授权的接口（登录前可访问）
    Route::group(function () {
        // 登录、验证码等公开接口
    });

    // 2. 需要登录，不验证访问权限
    Route::group(function () {
        // 基础信息获取等接口
    })->middleware(\app\http\middleware\admin\AdminAuthTokenMiddleware::class);

    // 3. 需要登录且验证权限
    Route::group(function () {
        // 业务功能接口
    })->middleware([
        \app\http\middleware\admin\AdminAuthTokenMiddleware::class,
        \app\http\middleware\admin\AdminCkeckRoleMiddleware::class
    ]);

})->prefix('admin.')->middleware([...]);

4.3 添加新路由示例

步骤1：创建控制器

// 文件：app/controller/admin/v1/custom/CustomController.php
<?php
namespace app\controller\admin\v1\custom;

use app\controller\admin\AuthController;
use app\services\custom\CustomServices;
use think\facade\App;

class CustomController extends AuthController
{
    protected CustomServices $services;

    public function __construct(App $app, CustomServices $services)
    {
        parent::__construct($app);
        $this->services = $services;
    }

    /**
     * 获取自定义列表
     */
    public function index()
    {
        $where = $this->request->getMore([
            ['keyword', ''],
            ['status', ''],
        ]);
        return app('json')->success($this->services->getList($where));
    }

    /**
     * 获取详情
     * @param int $id
     */
    public function read($id)
    {
        return app('json')->success($this->services->getInfo((int)$id));
    }

    /**
     * 保存数据
     */
    public function save()
    {
        $data = $this->request->postMore([
            ['name', ''],
            ['status', 1],
        ]);
        $this->services->saveData($data);
        return app('json')->success('保存成功');
    }
}

步骤2：在路由文件中添加路由

// 在 route/admin.php 中添加

/**
 * 自定义模块路由
 */
Route::group('custom', function () {
    // 自定义列表
    Route::get('list', 'v1.custom.CustomController/index')
        ->option(['real_name' => '自定义列表']);

    // 自定义详情
    Route::get('info/:id', 'v1.custom.CustomController/read')
        ->option(['real_name' => '自定义详情']);

    // 保存自定义数据
    Route::post('save', 'v1.custom.CustomController/save')
        ->option(['real_name' => '保存自定义数据']);

    // 使用资源路由
    Route::resource('item', 'v1.custom.CustomItem')->option(['real_name' => [
        'index'  => '获取项目列表',
        'read'   => '获取项目详情',
        'save'   => '保存项目',
        'update' => '修改项目',
        'delete' => '删除项目'
    ]]);

})->middleware([
    \app\http\middleware\admin\AdminAuthTokenMiddleware::class,
    \app\http\middleware\admin\AdminCkeckRoleMiddleware::class
])->middleware(\app\http\middleware\SystemLogMiddleware::class, 'admin');

4.4 访问地址

完整URL: http://域名/adminapi/custom/list

五、用户端添加路由 (api)

5.1 路由文件位置

route/api.php

5.2 路由结构说明

Route::group('api', function () {

    // 1. 公共回调接口（无需任何验证）
    Route::any('wechat/serve', 'v1.wechat.Wechat/serve');
    Route::any('pay/notify/:type', 'v1.Pay/notify');

    // 2. 登录类接口
    Route::group(function () {
        Route::post('login', 'v1.Login/login');
    });

    // 3. 无需授权接口（不登录可访问）
    Route::group(function () {
        // 商品列表、首页等公开接口
    });

    // 4. 授权不通过不抛异常（可选登录）
    Route::group(function () {
        // 获取用户相关但不强制登录的接口
    })->middleware(AuthTokenMiddleware::class, false);

    // 5. 必须授权接口（必须登录）
    Route::group(function () {
        // 用户中心、订单等需要登录的接口
    })->middleware(AuthTokenMiddleware::class, true);

})->prefix('api.')->middleware([...]);

5.3 添加新路由示例

步骤1：创建控制器

// 文件：app/controller/api/v1/custom/CustomApi.php
<?php
namespace app\controller\api\v1\custom;

use app\controller\api\AuthController;
use app\services\custom\CustomServices;
use think\facade\App;

class CustomApi extends AuthController
{
    protected CustomServices $services;

    public function __construct(App $app, CustomServices $services)
    {
        parent::__construct($app);
        $this->services = $services;
    }

    /**
     * 获取公开数据（无需登录）
     */
    public function getPublicData()
    {
        return app('json')->success($this->services->getPublicList());
    }

    /**
     * 获取用户数据（需要登录）
     */
    public function getUserData()
    {
        $uid = (int)$this->uid;
        return app('json')->success($this->services->getUserData($uid));
    }

    /**
     * 提交用户数据
     */
    public function submit()
    {
        $data = $this->request->postMore([
            ['content', ''],
            ['type', 1],
        ]);
        $this->services->submit((int)$this->uid, $data);
        return app('json')->success('提交成功');
    }
}

步骤2：在路由文件中添加路由

// 在 route/api.php 中添加

// 无需登录的接口
Route::group(function () {
    // 获取公开数据
    Route::get('custom/public', 'v1.custom.CustomApi/getPublicData')
        ->name('customPublicData');
});

// 可选登录的接口（登录和不登录都能访问，但获取的数据不同）
Route::group(function () {
    Route::get('custom/list', 'v1.custom.CustomApi/getList')
        ->name('customList');
})->middleware(AuthTokenMiddleware::class, false);

// 必须登录的接口
Route::group(function () {
    // 获取用户数据
    Route::get('custom/user_data', 'v1.custom.CustomApi/getUserData')
        ->name('customUserData');

    // 提交数据
    Route::post('custom/submit', 'v1.custom.CustomApi/submit')
        ->middleware(BlockerMiddleware::class)  // 防重复提交
        ->name('customSubmit');

})->middleware(AuthTokenMiddleware::class, true);

5.4 API版本管理

// V2版本路由
Route::group('v2', function () {

    // 无需授权
    Route::group(function () {
        Route::get('custom/new_list', 'v2.custom.CustomApi/newList');
    });

    // 需要授权
    Route::group(function () {
        Route::post('custom/new_submit', 'v2.custom.CustomApi/newSubmit');
    })->middleware(AuthTokenMiddleware::class, true);

});

六、门店端添加路由 (storeapi)

6.1 路由文件位置

route/store.php

6.2 路由结构说明

Route::group('storeapi', function () {

    // 1. 不需要登录不验证权限
    Route::group(function () {
        Route::post('login', 'Login/login');
    });

    // 2. 只需登录不验证权限
    Route::group(function () {
        Route::get('logo', 'Common/getLogo');
    })->middleware(AuthTokenMiddleware::class);

    // 3. 需登录验证权限
    Route::group(function () {
        // 业务接口
    })->middleware([AuthTokenMiddleware::class, StoreCkeckRoleMiddleware::class]);

    // 4. 按模块分组
    Route::group('product', function () {
        // 商品相关路由
    })->middleware([AuthTokenMiddleware::class, StoreCkeckRoleMiddleware::class]);

})->prefix('store.')->middleware([...]);

6.3 添加新路由示例

// 在 route/store.php 中添加

/**
 * 自定义门店功能路由
 */
Route::group('custom', function () {

    // 获取门店自定义列表
    Route::get('list', 'custom.StoreCustom/index')
        ->option(['real_name' => '获取门店自定义列表']);

    // 获取详情
    Route::get('info/:id', 'custom.StoreCustom/read')
        ->option(['real_name' => '获取自定义详情']);

    // 保存数据
    Route::post('save/:id', 'custom.StoreCustom/save')
        ->option(['real_name' => '保存自定义数据']);

    // 删除数据
    Route::delete('del/:id', 'custom.StoreCustom/delete')
        ->option(['real_name' => '删除自定义数据']);

    // 修改状态
    Route::put('set_status/:id/:status', 'custom.StoreCustom/set_status')
        ->option(['real_name' => '修改自定义状态']);

})->middleware([
    AuthTokenMiddleware::class, 
    StoreCkeckRoleMiddleware::class
])->middleware(\app\http\middleware\SystemLogMiddleware::class, 'store');

七、供应商端添加路由 (supplierapi)

7.1 路由文件位置

route/supplier.php

7.2 添加新路由示例

// 在 route/supplier.php 中添加

Route::group('custom', function () {

    // 供应商自定义功能
    Route::get('list', 'custom.SupplierCustom/index')
        ->option(['real_name' => '供应商自定义列表']);

    Route::post('save/:id', 'custom.SupplierCustom/save')
        ->option(['real_name' => '保存供应商自定义数据']);

})->middleware([
    AuthTokenMiddleware::class, 
    SupplierCkeckRoleMiddleware::class
])->middleware(\app\http\middleware\SystemLogMiddleware::class, 'supplier');

八、中间件配置说明

8.1 常用中间件

// 登录验证中间件
\app\http\middleware\admin\AdminAuthTokenMiddleware::class    // 平台后台
\app\http\middleware\api\AuthTokenMiddleware::class           // 用户端
\app\http\middleware\store\AuthTokenMiddleware::class         // 门店端
\app\http\middleware\supplier\AuthTokenMiddleware::class      // 供应商端

// 权限验证中间件
\app\http\middleware\admin\AdminCkeckRoleMiddleware::class    // 平台后台
\app\http\middleware\store\StoreCkeckRoleMiddleware::class    // 门店端
\app\http\middleware\supplier\SupplierCkeckRoleMiddleware::class // 供应商端

// 系统日志中间件
\app\http\middleware\SystemLogMiddleware::class

// 跨域中间件
\app\http\middleware\AllowOriginMiddleware::class

// 防重复提交中间件
\app\http\middleware\BlockerMiddleware::class

// 安装检测中间件
\app\http\middleware\InstallMiddleware::class

// 站点开启检测
\app\http\middleware\StationOpenMiddleware::class

8.2 中间件使用方式

// 单个中间件
Route::get('list', 'Controller/method')
    ->middleware(AuthTokenMiddleware::class);

// 多个中间件（数组形式）
Route::group(function () {
    // 路由定义
})->middleware([
    AuthTokenMiddleware::class,
    RoleMiddleware::class
]);

// 带参数的中间件
->middleware(AuthTokenMiddleware::class, true)   // true表示必须登录
->middleware(AuthTokenMiddleware::class, false)  // false表示可选登录
->middleware(SystemLogMiddleware::class, 'admin') // 记录admin模块日志

九、路由配置最佳实践

9.1 命名规范

// 路由路径使用小写+下划线
Route::get('user_info', '...');
Route::get('order_list', '...');

// 控制器方法使用驼峰命名
Route::get('list', 'Controller/getList');
Route::post('save', 'Controller/saveData');

// 路由名称使用驼峰命名
->name('getUserInfo');
->name('saveOrderData');

// real_name使用中文描述
->option(['real_name' => '获取用户信息']);

9.2 RESTful风格推荐

// 资源操作推荐使用对应的HTTP方法
Route::get('product', 'Product/index');         // 获取列表
Route::get('product/:id', 'Product/read');      // 获取详情
Route::post('product', 'Product/save');          // 创建
Route::put('product/:id', 'Product/update');     // 更新
Route::delete('product/:id', 'Product/delete');  // 删除

// 或使用资源路由
Route::resource('product', 'Product');

9.3 路由分组组织

// 按业务模块分组
Route::group('order', function () {
    Route::get('list', 'order.Order/index');
    Route::get('detail/:id', 'order.Order/read');

    // 子功能分组
    Route::group('refund', function () {
        Route::get('list', 'order.Refund/index');
        Route::post('apply/:id', 'order.Refund/apply');
    });
});

十、注意事项

10.1 路由冲突处理

// 带参数路由要放在固定路由后面
Route::get('product/list', 'Product/list');      // 先定义固定路由
Route::get('product/:id', 'Product/detail');     // 后定义参数路由

// 避免路由冲突
Route::get('product/info/:id', 'Product/info');  // 使用更具体的路径

10.2 权限菜单关联

新增路由后，需要在后台菜单管理中添加对应的菜单项才能使权限控制生效：

  1. 登录平台后台
  2. 进入：设置 -> 权限管理 -> 菜单管理
  3. 添加新菜单，设置对应的API路径

10.3 跨域配置

跨域已在全局中间件中配置：

// config/cookie.php
'header' => [
    'Access-Control-Allow-Origin'      => '*',
    'Access-Control-Allow-Headers'     => 'Authori-zation, Content-Type, ...',
    'Access-Control-Allow-Methods'     => 'GET, POST, PUT, DELETE, OPTIONS',
    'Access-Control-Allow-Credentials' => 'true',
]

十一、常见问题

Q1: 新增路由后404?

解决方案：

  1. 检查路由文件语法是否正确
  2. 确认控制器类和方法存在
  3. 清除路由缓存：php think clear
  4. 检查URL路径是否完整（包含前缀）

Q2: 权限验证不通过?

解决方案：

  1. 检查是否添加了正确的中间件
  2. 确认后台菜单是否已配置该路由
  3. 检查当前登录角色是否有该菜单权限

Q3: 路由参数获取不到?

解决方案：

// 控制器方法直接接收参数
public function detail($id) {
    // $id 自动注入
}

// 或通过request获取
public function detail() {
    $id = $this->request->param('id');
}

Q4: 如何调试路由?

// 查看所有已注册路由
php think route:list

// 在控制器中打印请求信息
dump($this->request->pathinfo());
dump($this->request->controller());
dump($this->request->action());
{{cateWiki.like_num}}人点赞
0人点赞
评论({{cateWiki.comment_num}}) {{commentWhere.order ? '评论从旧到新':'评论从新到旧'}} {{cateWiki.page_view_num}}人看过该文档
评论(0) {{commentWhere.order ? '评论从旧到新':'评论从新到旧'}} 20人看过该文档
评论
{{item.user ? item.user.nickname : ''}} （自评）
{{item.content}}
{{item.create_time}} 删除
{{item.like ? item.like.like_num : 0}} {{replyIndex == index ? '取消回复' : '回复'}}
评论
{{items.user ? items.user.nickname : '暂无昵称'}} （自评）
{{items.content}}
{{items.create_time}} 删除
{{items.like ? items.like.like_num : 0}} {{replyIndexJ == (index+'|'+indexJ) ? '取消回复' : '回复'}}
评论
目录
  • {{item}}
搜索结果 为您找到{{wikiCount}}条结果
位置： {{path.name}} {{(i+1) == item.catalogue.path_data.length ? '':'/'}}
{{item.page_view_num}} {{item.like ? item.like.like_num : 0}} {{item.comment ? item.comment.comment_num : 0}}