96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
8.7 KiB
角色管理API
**本文档中引用的文件** - [model.go](file://api/sys_role/v1/model.go) - [sys_role.go](file://api/sys_role/v1/sys_role.go) - [sys_role_v1_role_add.go](file://internal/controller/sys_role/sys_role_v1_role_add.go) - [sys_role_v1_role_edit.go](file://internal/controller/sys_role/sys_role_v1_role_edit.go) - [sys_role_v1_role_delete.go](file://internal/controller/sys_role/sys_role_v1_role_delete.go) - [sys_role_v1_role_list.go](file://internal/controller/sys_role/sys_role_v1_role_list.go) - [sys_role_v1_role_get.go](file://internal/controller/sys_role/sys_role_v1_role_get.go) - [v_1_sys_role.go](file://internal/model/entity/v_1_sys_role.go) - [sys_role.go](file://internal/service/sys_role.go) - [rbac_model.conf](file://resource/casbin/rbac_model.conf)目录
简介
本文档详细描述了角色管理API的设计与实现，涵盖角色的增删改查操作。重点说明了角色在RBAC权限控制模型中的核心作用，以及如何通过角色实现细粒度的访问控制。文档详细阐述了创建角色、更新角色、删除角色和获取角色列表等端点的HTTP方法、URL模式、请求/响应模式和认证机制，并提供实际使用示例。
项目结构
角色管理功能主要分布在API层和内部服务层，采用分层架构设计。API定义位于api/sys_role/v1/目录下，控制器实现位于internal/controller/sys_role/目录，服务接口定义在internal/service/sys_role.go，实体模型定义在internal/model/entity/v_1_sys_role.go。
graph TD
A[API层] --> B[Controller层]
B --> C[Service层]
C --> D[DAO层]
D --> E[数据库]
subgraph "API定义"
A1[sys_role.go]
A2[model.go]
end
subgraph "控制器"
B1[sys_role_v1_role_add.go]
B2[sys_role_v1_role_edit.go]
B3[sys_role_v1_role_delete.go]
B4[sys_role_v1_role_list.go]
B5[sys_role_v1_role_get.go]
end
subgraph "服务层"
C1[sys_role.go]
end
subgraph "数据模型"
D1[v_1_sys_role.go]
end
Diagram sources
Section sources
核心组件
角色管理API的核心组件包括角色实体模型、API请求/响应结构、控制器实现和服务接口。系统基于RBAC（基于角色的访问控制）模型，通过角色与权限规则的关联实现细粒度的访问控制。每个角色包含名称、状态、排序、备注等基本信息，并通过菜单ID列表与具体权限关联。
Section sources
架构概述
系统采用典型的分层架构，从上至下分为API层、控制器层、服务层和数据访问层。API层定义了HTTP端点的路由、方法和参数结构；控制器层处理请求验证和转发；服务层包含核心业务逻辑；DAO层负责与数据库交互。权限控制基于Casbin实现，配置文件位于resource/casbin/rbac_model.conf。
graph TB
subgraph "表现层"
A[HTTP API]
end
subgraph "应用层"
B[Controller]
end
subgraph "业务逻辑层"
C[Service]
end
subgraph "数据访问层"
D[DAO]
E[Casbin]
end
subgraph "数据层"
F[MySQL]
end
A --> B --> C --> D --> F
C --> E
Diagram sources
详细组件分析
角色管理端点分析
角色管理API提供了完整的CRUD操作，包括创建、读取、更新和删除角色。所有端点均通过统一的认证机制保护，确保只有授权用户才能执行相应操作。
API端点定义
flowchart TD
A[角色列表] --> |GET /role/list| B[分页查询角色]
C[获取角色参数] --> |GET /role/getParams| D[获取编辑参数]
E[添加角色] --> |POST /role/add| F[创建新角色]
G[获取角色信息] --> |GET /role/get| H[查询单个角色]
I[修改角色] --> |PUT /role/edit| J[更新角色信息]
K[删除角色] --> |DELETE /role/delete| L[批量删除角色]
Diagram sources
请求/响应模型
classDiagram
class RoleListReq {
+string RoleName
+string Status
+CommonPageReq
}
class RoleListRes {
+CommonPageRes[*V1SysRole]
}
class RoleAddReq {
+string Name
+uint Status
+uint ListOrder
+string Remark
+[]uint MenuIds
}
class RoleAddRes {
}
class RoleEditReq {
+int64 Id
+string Name
+uint Status
+uint ListOrder
+string Remark
+[]uint MenuIds
}
class RoleEditRes {
}
class RoleDeleteReq {
+[]int64 Ids
}
class RoleDeleteRes {
}
class V1SysRole {
+uint Id
+uint Status
+uint ListOrder
+string Name
+string Remark
+uint DataScope
+*gtime.Time CreatedAt
+*gtime.Time UpdatedAt
}
RoleListReq --> RoleListRes : "响应"
RoleAddReq --> RoleAddRes : "响应"
RoleEditReq --> RoleEditRes : "响应"
RoleDeleteReq --> RoleDeleteRes : "响应"
RoleListRes --> V1SysRole : "包含"
Diagram sources
RBAC权限模型分析
系统采用标准的RBAC（基于角色的访问控制）模型，通过Casbin实现权限控制。角色与权限规则通过多对多关系关联，实现灵活的权限分配。
erDiagram
ROLE ||--o{ ROLE_MENU : "拥有"
ROLE {
uint id PK
string name
uint status
uint list_order
string remark
uint data_scope
datetime created_at
datetime updated_at
}
MENU ||--o{ ROLE_MENU : "被分配给"
MENU {
uint id PK
string name
string path
string component
uint status
}
ROLE_MENU {
uint role_id FK
uint menu_id FK
}
Diagram sources
Section sources
依赖分析
角色管理功能依赖于多个核心组件，包括认证中间件、Casbin权限引擎、数据库访问层和通用工具库。服务层通过接口定义与具体实现解耦，便于测试和维护。
graph TD
A[角色管理API] --> B[认证中间件]
A --> C[Casbin权限引擎]
A --> D[MySQL数据库]
A --> E[分页工具]
A --> F[参数验证]
A --> G[错误处理]
B --> H[JWT令牌]
C --> I[rbac_model.conf]
D --> J[DAO层]
F --> K[GoFrame验证器]
G --> L[统一错误码]
Diagram sources
Section sources
性能考虑
角色管理API在设计时考虑了性能优化，包括数据库索引优化、查询结果缓存和批量操作支持。建议在高并发场景下对角色列表接口启用Redis缓存，减少数据库压力。对于批量删除操作，采用事务处理确保数据一致性。
故障排除指南
常见问题包括权限不足、参数验证失败和数据库连接错误。系统采用统一的错误处理机制，返回标准化的错误码和消息。开发人员应检查请求头中的认证令牌、请求参数的格式和必填字段，以及服务日志中的详细错误信息。
Section sources
结论
角色管理API提供了完整的角色生命周期管理功能，基于RBAC模型实现了灵活的权限控制。系统架构清晰，分层合理，便于维护和扩展。通过标准化的API设计和统一的错误处理，确保了接口的易用性和可靠性。建议在生产环境中启用适当的缓存策略和监控告警，以保障系统的稳定运行。