修复路由命名规范问题

任务时间: 2025年06月04日 12:04
任务类型: 路由规范化
优先级: 中等
状态: ✅ 已完成

任务概述

检查并修复项目中所有不符合路由命名规范的问题，将使用斜杠(/)分割的路由改为使用连字符(-)，确保路由命名的一致性和规范性。

发现的问题

通过全面检查项目中的Resource注解和菜单数据库，发现以下路由命名问题：

1. 控制器路由注解问题

控制器	原路由	修复后路由	状态
OAuthClientController	`oauth/clients`	`oauth-clients`	✅ 已修复
ConfigAController	`system/config_admin`	`system-config-admin`	✅ 已修复
ConfigController	`system/config`	`system-config`	✅ 已修复
ItemChestConfigController	`game-items/chest-configs`	`game-items-chest-configs`	✅ 已修复

2. 菜单数据库URI问题

菜单ID	菜单名称	原URI	修复后URI	状态
213	OAuth认证	`oauth/clients`	`oauth-clients`	✅ 已修复
204	设置管理	`system/config_admin`	`system-config-admin`	✅ 已修复
9	系统配置	`system/config`	`system-config`	✅ 已修复
515	宝箱配置管理	`game-items/chest-configs`	`game-items-chest-configs`	✅ 已修复

修复过程

1. 问题发现

使用以下命令查找所有使用Resource注解且包含斜杠的控制器：

find app/Module -name "*.php" -exec grep -l "#\[Resource" {} \;
grep -n "#\[Resource.*/" app/Module/*/AdminControllers/*.php

2. 数据库检查

查询菜单表中所有包含斜杠的URI：

SELECT id, title, uri FROM kku_admin_menu 
WHERE uri LIKE '%/%' AND uri NOT LIKE '%{%}' 
ORDER BY uri

3. 逐一修复

OAuthClientController

// 修复前
#[Resource('oauth/clients', except: ['destroy'])]

// 修复后  
#[Resource('oauth-clients', except: ['destroy'])]

ConfigAController

// 修复前
#[Resource('system/config_admin',names: 'dcat.admin.config_admin')]

// 修复后
#[Resource('system-config-admin',names: 'dcat.admin.system-config-admin')]

ConfigController

// 修复前
#[Resource('system/config', names: 'dcat.admin.config')]

// 修复后
#[Resource('system-config', names: 'dcat.admin.system-config')]

ItemChestConfigController

// 修复前
#[Resource('game-items/chest-configs', names: 'dcat.admin.game-items.chest-configs')]

// 修复后
#[Resource('game-items-chest-configs', names: 'dcat.admin.game-items-chest-configs')]

4. 数据库更新

使用MCP执行SQL更新菜单URI：

UPDATE kku_admin_menu SET uri = 'oauth-clients' WHERE uri = 'oauth/clients';
UPDATE kku_admin_menu SET uri = 'system-config-admin' WHERE uri = 'system/config_admin';
UPDATE kku_admin_menu SET uri = 'system-config' WHERE uri = 'system/config';
UPDATE kku_admin_menu SET uri = 'game-items-chest-configs' WHERE uri = 'game-items/chest-configs';

排除的路由

以下系统核心路由保持不变，因为它们是Laravel Admin框架的核心功能：

路由	说明	保留原因
`auth/extensions`	扩展管理	Laravel Admin核心功能
`auth/menu`	菜单管理	Laravel Admin核心功能
`auth/permissions`	权限管理	Laravel Admin核心功能
`auth/roles`	角色管理	Laravel Admin核心功能
`auth/users`	管理员管理	Laravel Admin核心功能
`dev/router`	路由管理	开发工具

验证结果

1. 控制器检查

# 检查是否还有使用斜杠的Resource注解
find app/Module -name "*.php" -exec grep -l "Resource.*/" {} \;
# 结果：无输出，说明所有问题已修复

2. 数据库验证

SELECT id, title, uri FROM kku_admin_menu 
WHERE uri LIKE '%/%' AND uri NOT LIKE '%{%}' 
AND uri NOT LIKE 'auth/%' AND uri NOT LIKE 'dev/%' 
ORDER BY uri;
# 结果：0行，说明所有业务模块路由已修复

路由命名规范

正确的命名方式

✅ 使用连字符分割: oauth-clients
✅ 使用连字符分割: system-config-admin
✅ 使用连字符分割: game-items-chest-configs

错误的命名方式

❌ 使用斜杠分割: oauth/clients
❌ 使用下划线: config_admin
❌ 混合使用: game-items/chest-configs

技术细节

Resource注解规范

#[Resource('resource-name', names: 'dcat.admin.resource-name')]

菜单URI规范

URI应与Resource注解中的resource参数保持一致
使用连字符(-)而不是斜杠(/)或下划线(_)
保持简洁明了，体现资源层级关系

路由名称规范

names参数应与resource参数保持一致
使用点号(.)分割命名空间
格式：dcat.admin.{resource-name}

影响评估

正面影响

路由一致性: 所有业务模块路由命名统一规范
维护性提升: 更容易理解和维护路由结构
RESTful规范: 符合现代Web开发最佳实践
URL美观: 更简洁美观的URL结构

潜在风险

缓存问题: 可能需要清理路由缓存
书签失效: 用户保存的书签可能失效
文档更新: 需要更新相关文档和说明

风险缓解

部署后清理应用缓存
通知用户更新书签
更新相关文档和API说明

后续建议

1. 代码规范

在代码审查中检查路由命名规范
建立路由命名检查工具
在开发文档中明确路由命名规范

2. 自动化检查

添加CI/CD检查，确保新增路由符合规范
定期扫描项目中的路由命名问题
建立路由命名规范的单元测试

3. 文档维护

更新开发文档中的路由规范说明
创建路由命名最佳实践指南
维护路由变更记录

总结

成功修复了项目中所有不符合规范的路由命名问题：

修复范围: 4个控制器，4个菜单项
修复方式: 统一使用连字符替代斜杠
验证结果: 所有业务模块路由已符合规范
系统稳定: 保留核心系统路由不变

路由命名规范化工作已完成，项目现在具有更好的一致性和可维护性。

041204-修复路由命名规范问题.md 6.2 KB History Raw