danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/API端点参考/权限管理API/菜单管理API.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

13 KiB
Raw Blame History

菜单管理API

**本文档中引用的文件** - [menu.go](file://api/authority/v1/menu.go) - [model.go](file://api/authority/v1/model.go) - [authority_v1_menu_list.go](file://internal/controller/authority/authority_v1_menu_list.go) - [authority_v1_menu_create.go](file://internal/controller/authority/authority_v1_menu_create.go) - [authority_v1_menu_update.go](file://internal/controller/authority/authority_v1_menu_update.go) - [authority_v1_menu_delete.go](file://internal/controller/authority/authority_v1_menu_delete.go) - [sys_auth_rule.go](file://internal/model/sys_auth_rule.go) - [common.go](file://api/commonApi/common.go) - [rbac_model.conf](file://resource/casbin/rbac_model.conf) - [sys_auth_rule.go](file://internal/service/sys_auth_rule.go) - [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概述
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

本文档详细描述了菜单管理API的设计与实现，涵盖菜单的增删改查操作。该API基于RBAC（基于角色的访问控制）模型，通过菜单权限控制用户界面访问权限。文档详细说明了创建菜单、更新菜单、删除菜单和获取菜单列表等端点的HTTP方法、URL模式、请求/响应模式和认证机制，并提供实际使用示例。同时，文档还解释了菜单权限在RBAC模型中的作用，以及错误处理策略、安全考虑和性能优化建议。

项目结构

菜单管理API的实现分布在多个目录中，主要涉及API定义、控制器逻辑和数据模型。API端点定义位于api/authority/v1/目录下，控制器实现位于internal/controller/authority/目录中，数据模型定义在internal/model/和internal/model/entity/目录中。服务层接口在internal/service/目录中声明，而RBAC权限模型配置位于resource/casbin/目录下。

graph TB
subgraph "API层"
A[menu.go]
B[model.go]
end
subgraph "控制器层"
C[authority_v1_menu_list.go]
D[authority_v1_menu_create.go]
E[authority_v1_menu_update.go]
F[authority_v1_menu_delete.go]
end
subgraph "服务层"
G[sys_auth_rule.go]
end
subgraph "数据模型层"
H[sys_auth_rule.go]
I[v_1_sys_auth_rule.go]
end
subgraph "公共组件"
J[common.go]
end
subgraph "权限配置"
K[rbac_model.conf]
end
A --> C
B --> C
C --> G
G --> H
H --> I
J --> A
K --> G

Diagram sources

Section sources

核心组件

菜单管理API的核心组件包括菜单的增删改查操作，这些操作通过RESTful端点暴露。API使用GoFrame框架构建，通过结构体标签定义HTTP路由、方法和请求参数。菜单数据模型支持树形结构，允许创建多级菜单体系。权限控制基于Casbin实现的RBAC模型，确保只有授权用户才能执行相应操作。

Section sources

架构概述

菜单管理API采用分层架构设计，包括API层、控制器层、服务层和数据访问层。API层定义了HTTP端点和数据传输对象（DTO），控制器层处理请求并调用服务层，服务层包含业务逻辑并协调数据访问，数据访问层负责与数据库交互。整个系统通过RBAC模型进行权限控制，确保操作的安全性。

graph TD
Client[客户端] --> API[API层]
API --> Controller[控制器层]
Controller --> Service[服务层]
Service --> DAO[数据访问层]
DAO --> DB[(数据库)]
Service --> Casbin[RBAC权限控制]
Casbin --> rbac_model[rbac_model.conf]
style Client fill:#f9f,stroke:#333
style DB fill:#ccf,stroke:#333
style rbac_model fill:#cfc,stroke:#333

Diagram sources

详细组件分析

菜单创建分析

菜单创建功能允许系统管理员创建新的菜单项。该功能通过POST请求实现，请求体包含菜单的详细信息，如名称、标题、类型、路径等。系统验证输入数据的完整性后，将其持久化到数据库中。

API端点定义

classDiagram
class MenuCreateReq {
+string path "/auth/menu/create"
+string method "post"
+string summary "创建菜单信息"
+SysAuthRuleReq SysAuthRuleReq
}
class SysAuthRuleReq {
+string name "规则名称"
+string title "规则名称"
+uint PID "父ID"
+uint MenuType "类型 0目录 1菜单 2按钮"
+int Weigh "权重"
+uint IsHide "显示状态"
+string Path "路由地址"
+int IsAdmin "是否管理员独享 1是2.否"
+string Component "组件路径"
}
MenuCreateReq --> SysAuthRuleReq : "包含"

Diagram sources

Section sources

菜单更新分析

菜单更新功能允许修改现有菜单项的属性。该功能通过POST请求实现，需要提供菜单的ID和要更新的字段。系统会验证用户权限，确保只有授权用户才能修改菜单。

API端点定义

classDiagram
class MenuUpdateReq {
+string path "/auth/menu/update"
+string method "post"
+string summary "修改菜单信息"
+SysAuthRuleWithID SysAuthRuleWithID
}
class SysAuthRuleWithID {
+SysAuthRuleReq SysAuthRuleReq
+uint ID "ID"
}
class SysAuthRuleReq {
+string name "规则名称"
+string title "规则名称"
+uint PID "父ID"
+uint MenuType "类型 0目录 1菜单 2按钮"
+int Weigh "权重"
+uint IsHide "显示状态"
+string Path "路由地址"
+int IsAdmin "是否管理员独享 1是2.否"
+string Component "组件路径"
}
MenuUpdateReq --> SysAuthRuleWithID : "包含"
SysAuthRuleWithID --> SysAuthRuleReq : "继承"

Diagram sources

Section sources

菜单删除分析

菜单删除功能允许移除不再需要的菜单项。该功能通过DELETE请求实现，需要提供要删除的菜单ID。系统会检查菜单是否存在子菜单，如果有则一并删除。

API端点定义

classDiagram
class MenuDeleteReq {
+string path "/auth/menu/delete"
+string method "delete"
+string summary "删除菜单信息"
+uint ID "ID"
}
class CommonIntId {
+uint ID "ID"
}
MenuDeleteReq --> CommonIntId : "继承"

Diagram sources

Section sources

菜单列表获取分析

菜单列表获取功能返回系统中所有菜单的树形结构。该功能通过GET请求实现，无需请求体，返回包含所有菜单及其层级关系的数据。

API端点定义

classDiagram
class MenuListReq {
+string path "/auth/menu/getList"
+string method "get"
+string summary "获取菜单信息"
}
class MenuListRes {
+CommonDataRes[*SysAuthRule] List
}
class SysAuthRule {
+uint ID
+string name
+string title
+uint MenuType
+int Weigh
+uint IsHide
+string Path
+int IdAdmin
+string Component
+*SysAuthRule[] Children
}
MenuListRes --> SysAuthRule : "包含"
SysAuthRule --> SysAuthRule : "children"

Diagram sources

Section sources

RBAC权限模型分析

RBAC（基于角色的访问控制）模型定义了用户、角色和权限之间的关系。菜单权限作为系统权限的一部分，通过Casbin引擎进行管理。该模型确保用户只能访问其角色所允许的菜单项。

权限模型配置

graph TD
subgraph "RBAC模型"
Request[请求定义 r = sub, obj, act]
Policy[策略定义 p = sub, obj, act]
Role[角色定义 g = _, _]
Effect[策略效果 e = some(where (p.eft == allow))]
Matcher[匹配器 m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act]
end
Request --> Matcher
Policy --> Matcher
Role --> Matcher
Effect --> Matcher
style Request fill:#f96,stroke:#333
style Policy fill:#f96,stroke:#333
style Role fill:#f96,stroke:#333
style Effect fill:#f96,stroke:#333
style Matcher fill:#6f9,stroke:#333

Diagram sources

Section sources

依赖分析

菜单管理API的组件之间存在明确的依赖关系。API层依赖于公共组件和数据模型，控制器层依赖于API定义和服务层，服务层依赖于数据模型和实体定义。整个系统通过RBAC模型进行权限控制，确保操作的安全性。

graph LR
commonApi[commonApi] --> api[api/authority/v1]
model[internal/model] --> api
api --> controller[internal/controller/authority]
controller --> service[internal/service]
service --> entity[internal/model/entity]
service --> casbin[resource/casbin]
style commonApi fill:#cfc,stroke:#333
style model fill:#cfc,stroke:#333
style api fill:#cf9,stroke:#333
style controller fill:#9cf,stroke:#333
style service fill:#9cf,stroke:#333
style entity fill:#cfc,stroke:#333
style casbin fill:#cfc,stroke:#333

Diagram sources

Section sources

性能考虑

菜单管理API的性能主要受数据库查询和树形结构构建的影响。获取菜单列表时，系统需要从数据库加载所有菜单数据并构建树形结构，这可能成为性能瓶颈。建议对菜单数据进行适当的缓存，以减少数据库查询次数。同时，对于大型菜单体系，可以考虑实现分页或懒加载机制。

故障排除指南

当菜单管理API出现问题时，应首先检查请求参数是否正确，特别是ID字段是否有效。对于创建和更新操作，确保所有必填字段都已提供。如果遇到权限错误，检查用户角色是否具有执行相应操作的权限。在删除菜单时，如果系统返回错误，可能是由于外键约束或其他业务规则限制。

Section sources

结论

菜单管理API提供了一套完整的菜单增删改查功能，通过清晰的RESTful端点设计和严格的RBAC权限控制，确保了系统的安全性和可用性。API的设计考虑了可扩展性和性能，为前端界面提供了灵活的菜单配置能力。通过遵循本文档中的指导，开发者可以有效地使用和维护这套API系统。