junhong_cmp_fiber/docs/permission-check-usage.md

权限检查使用指南

概述

权限检查服务 (PermissionService.CheckPermission) 现已完全实现，支持基于角色的权限验证（RBAC）。

核心功能

• ✅ 完整的权限查询链：账号 → 角色列表 → 权限列表 → 匹配检查
• ✅ 超级管理员特权：自动跳过权限检查，拥有所有权限
• ✅ 平台过滤：支持 all/web/h5 三种端口类型的权限隔离
• ✅ 错误处理：详细的错误信息和日志记录
• ✅ 性能优化：使用批量查询和去重，3次数据库查询完成权限检查
• ✅ Redis 缓存：自动缓存用户权限列表，大幅提升查询性能（TTL 30分钟）

工作原理

权限检查流程（带缓存）

1. 检查用户类型
   ↓ 如果是超级管理员 → 直接返回 true
   ↓ 否则继续
   
2. 查询 Redis 缓存
   ↓ Key: permission:user:{userID}:list
   ↓ 缓存命中 → 跳到步骤 6
   ↓ 缓存未命中 → 继续
   
3. 查询用户的角色 ID 列表
   ↓ AccountRoleStore.GetRoleIDsByAccountID(userID)
   ↓ 如果为空 → 返回 false（用户无角色）
   
4. 查询角色的权限 ID 列表（自动去重）
   ↓ RolePermissionStore.GetPermIDsByRoleIDs(roleIDs)
   ↓ 如果为空 → 返回 false（角色无权限）
   
5. 查询权限详情列表
   ↓ PermissionStore.GetByIDs(permIDs)
   ↓ 将结果写入 Redis 缓存（TTL 30分钟）
   
6. 遍历权限列表，匹配 permCode 和 platform
   ↓ 找到匹配 → 返回 true
   ↓ 未找到 → 返回 false

Platform 匹配规则

权限的 platform	请求的 platform	是否匹配
all	web	✅ 匹配
all	h5	✅ 匹配
web	web	✅ 匹配
web	h5	❌ 不匹配
h5	h5	✅ 匹配
h5	web	❌ 不匹配

在路由中使用权限中间件

基本用法

import (
	"github.com/break/junhong_cmp_fiber/pkg/middleware"
	"github.com/break/junhong_cmp_fiber/pkg/constants"
	"github.com/gofiber/fiber/v2"
)

// 初始化权限中间件配置
permissionConfig := middleware.PermissionConfig{
	PermissionChecker: permissionService, // Permission Service 实例
	Platform:          constants.PlatformWeb, // 指定端口类型
	SkipSuperAdmin:    true, // 超级管理员跳过检查（推荐）
}

// 单个权限保护
app.Post("/api/v1/users", 
	middleware.RequirePermission("user:create", permissionConfig),
	userHandler.Create,
)

// 需要任意一个权限（OR 逻辑）
app.Get("/api/v1/orders", 
	middleware.RequireAnyPermission([]string{"order:view", "order:manage"}, permissionConfig),
	orderHandler.List,
)

// 需要所有权限（AND 逻辑）
app.Delete("/api/v1/users/:id", 
	middleware.RequireAllPermissions([]string{"user:delete", "user:manage"}, permissionConfig),
	userHandler.Delete,
)

H5 端口示例

// H5 端口权限配置
h5PermissionConfig := middleware.PermissionConfig{
	PermissionChecker: permissionService,
	Platform:          constants.PlatformH5,
	SkipSuperAdmin:    true,
}

// H5 端口受保护路由
app.Get("/api/h5/profile", 
	middleware.RequirePermission("profile:view", h5PermissionConfig),
	profileHandler.Get,
)

完整示例

func setupRoutes(app *fiber.App, handlers *bootstrap.Handlers, permissionService *permission.Service) {
	// 认证中间件（必须先执行，提供用户上下文）
	authMiddleware := middleware.Auth(middleware.AuthConfig{
		TokenValidator: tokenValidator,
		SkipPaths:      []string{"/health", "/api/v1/auth/login"},
	})

	// 权限中间件配置
	webPermissionConfig := middleware.PermissionConfig{
		PermissionChecker: permissionService,
		Platform:          constants.PlatformWeb,
		SkipSuperAdmin:    true,
	}

	// API 路由组
	api := app.Group("/api/v1", authMiddleware) // 先认证
	
	// 用户管理（需要权限）
	users := api.Group("/users")
	users.Get("/", 
		middleware.RequirePermission("user:list", webPermissionConfig),
		handlers.Account.List,
	)
	users.Post("/", 
		middleware.RequirePermission("user:create", webPermissionConfig),
		handlers.Account.Create,
	)
	users.Put("/:id", 
		middleware.RequirePermission("user:update", webPermissionConfig),
		handlers.Account.Update,
	)
	users.Delete("/:id", 
		middleware.RequirePermission("user:delete", webPermissionConfig),
		handlers.Account.Delete,
	)
	
	// 角色管理（需要权限）
	roles := api.Group("/roles")
	roles.Get("/", 
		middleware.RequirePermission("role:list", webPermissionConfig),
		handlers.Role.List,
	)
	roles.Post("/", 
		middleware.RequirePermission("role:create", webPermissionConfig),
		handlers.Role.Create,
	)
}

权限编码规范

命名格式

格式: module:action
示例: user:create, order:view, role:delete

推荐的权限编码

模块	操作	权限编码
用户管理	列表	user:list
用户管理	查看	user:view
用户管理	创建	user:create
用户管理	更新	user:update
用户管理	删除	user:delete
角色管理	列表	role:list
角色管理	分配权限	role:assign_permission
权限管理	查看	permission:view
订单管理	审核	order:approve

性能说明

查询性能

首次查询（缓存未命中）:

• 查询次数: 3次数据库查询（角色查询 + 权限查询 + 权限详情）+ 1次 Redis 写入
• 预估耗时:
  • 本地数据库: < 10ms
  • 远程数据库: < 20ms

后续查询（缓存命中）:

• 查询次数: 1次 Redis 查询
• 预估耗时: < 2ms

优化措施:

• Redis 缓存：自动缓存用户权限列表，TTL 30分钟
• 批量查询：使用 GetByIDs 和 GetPermIDsByRoleIDs
• 自动去重：Distinct() 避免重复权限
• 超级管理员短路：不执行数据库或缓存查询

Redis 缓存机制

缓存策略

缓存 Key: permission:user:{userID}:list
缓存值: JSON 数组 [{"perm_code":"user:list","platform":"web"},...]
过期时间: 30 分钟
失效策略: 角色/权限变更时自动清除相关用户缓存

自动失效场景

系统会在以下操作后自动清除相关用户的权限缓存：

1. 用户角色变更时（AccountRoleStore）:

   • 添加角色：Create(), BatchCreate()
   • 删除角色：Delete(), DeleteByAccountID()

2. 角色权限变更时（RolePermissionStore）:

   • 添加权限：Create(), BatchCreate()
   • 删除权限：Delete(), DeleteByRoleID()
   • 清除该角色下所有用户的缓存

缓存性能提升

根据测试结果：

• 首次查询: ~18ms（3次数据库查询）
• 缓存命中: ~1.5ms（1次 Redis 查询）
• 性能提升: ~12倍（缓存命中时）

缓存一致性保证

• 写操作触发清除: 所有角色/权限变更操作都会自动清除相关缓存
• TTL兜底: 即使清除失败，缓存也会在30分钟后过期
• 无缓存降级: Redis 不可用时自动降级到数据库查询

错误处理

错误类型

场景	返回值	错误信息
超级管理员	(true, nil)	-
有权限	(true, nil)	-
无权限	(false, nil)	-
用户无角色	(false, nil)	-
角色无权限	(false, nil)	-
数据库查询失败	(false, error)	"查询用户角色失败: ..."

中间件错误响应

权限中间件会自动将错误转换为 HTTP 响应：

场景	HTTP 状态码	错误码	消息
未认证	401	未定义	"未认证的请求"
无权限	403	未定义	"无权限访问该资源"
权限检查失败	500	CodeInternalError	"权限检查失败"

测试

单元测试

已覆盖以下场景：

权限检查功能:

• ✅ 超级管理员自动拥有所有权限
• ✅ 有权限的用户返回 true
• ✅ 无权限的用户返回 false
• ✅ platform=all 的权限在 web 端可访问
• ✅ platform=web 的权限在 h5 端不可访问
• ✅ platform=web 的权限在 web 端可访问
• ✅ 用户无角色返回 false
• ✅ 角色无权限返回 false

缓存功能:

• ✅ 首次查询缓存未命中，写入缓存
• ✅ 后续查询缓存命中，直接返回
• ✅ 缓存 TTL 设置为 30 分钟
• ✅ 角色变更后缓存自动清除

运行测试：

# 权限检查测试
go test -v ./tests/unit/permission_check_test.go

# 缓存功能测试
go test -v ./tests/unit/permission_cache_test.go

注意事项

1. 认证在前，权限在后：权限中间件依赖认证中间件提供的用户上下文，必须先执行认证
2. 超级管理员特权：建议启用 SkipSuperAdmin: true，超级管理员自动拥有所有权限
3. 权限编码格式：必须使用 module:action 格式，否则创建权限时会失败
4. 平台隔离：确保权限的 platform 字段与请求的 platform 参数一致
5. 错误不影响安全：查询失败时返回 false（fail-closed），不会误放行

相关文档

• 设计文档
• 提案文档
• 权限模型说明