permission

README

permission — 路由权限元数据

为 Chi Router 路由注册提供权限元数据（Meta），供权限同步工具、文档生成与中间件鉴权读取。

功能

• 用 permission.Get/Post/Put/Delete/... 替代 r.Get/Post/...，在注册路由时附加权限描述
• 中间件可通过 permission.ExtractMeta(handler) 从 handler 中提取元数据
• 支持标记路由为公开（IsPublic: true）或受保护

快速开始

import "github.com/leeforge/framework/permission"

func (h *UserHandler) Routes(r chi.Router) {
    // 公开路由（无需鉴权）
    permission.Post(r, "/auth/login", h.Login, permission.Public("用户登录"))

    // 受保护路由（需要 users:read 权限）
    permission.Get(r, "/users", h.List, permission.Private("获取用户列表", "users:read"))
    permission.Get(r, "/users/{id}", h.Get, permission.Private("获取用户详情", "users:read"))
    permission.Post(r, "/users", h.Create, permission.Private("创建用户", "users:write"))
    permission.Put(r, "/users/{id}", h.Update, permission.Private("更新用户", "users:write"))
    permission.Delete(r, "/users/{id}", h.Delete, permission.Private("删除用户", "users:delete"))
}

Meta 结构

type Meta struct {
    Description string   // 接口描述（用于文档）
    IsPublic    bool     // 是否公开（跳过鉴权）
    Permissions []string // 所需权限码列表（如 "users:read"）
}

创建元数据

// 公开路由
meta := permission.Public("用户注册")
meta := permission.Public("健康检查")

// 受保护路由（支持多权限码）
meta := permission.Private("发布文章", "articles:write", "articles:publish")

提取元数据（在中间件中使用）

func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        meta, ok := permission.ExtractMeta(next)
        if ok && meta.IsPublic {
            next.ServeHTTP(w, r) // 公开路由跳过鉴权
            return
        }
        // 继续鉴权逻辑...
    })
}

与权限同步工具配合

框架的权限同步工具（tools/permission-syncer）会遍历所有注册路由，提取 Meta 并同步到 APIPermission 实体：

新增路由 → permission.Private(...) → 权限同步工具 → APIPermission 表 → Casbin 规则

注意事项

• 所有需要鉴权的路由都应使用此包注册，禁止使用裸 r.Get/Post/...，否则权限信息丢失
• 权限码命名约定：{资源}:{操作}，如 users:read、articles:write
• permission.ExtractMeta 能穿透 Chi 的 ChainHandler 包装层

Documentation

Index

• func Connect(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Delete(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Get(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Head(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Options(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Patch(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Post(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Put(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Register(r chi.Router, method, path string, handler http.Handler, meta Meta)
• func Trace(r chi.Router, path string, handler http.HandlerFunc, meta Meta)
• func Wrap(handler http.Handler, meta Meta) http.Handler
• type Mapping
• type Meta
  • func ExtractMeta(handler http.Handler) (Meta, bool)
  • func Private(description string, codes ...string) Meta
  • func Public(description string, codes ...string) Meta
• type MetaHandler
  • func (h *MetaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Permission
• type RouteInfo
• type Scope
• type Snapshot
  • func BuildSnapshot(routes []RouteInfo) Snapshot
  • func SnapshotFromRouter(r chi.Routes) (Snapshot, error)
• type Status

Functions

func Connect

func Connect(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Connect registers a CONNECT route with metadata.

func Delete

func Delete(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Delete registers a DELETE route with metadata.

func Get

func Get(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Get registers a GET route with metadata.

func Head

func Head(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Head registers a HEAD route with metadata.

func Options

func Options(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Options registers an OPTIONS route with metadata.

func Patch

func Patch(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Patch registers a PATCH route with metadata.

func Post

func Post(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Post registers a POST route with metadata.

func Put

func Put(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Put registers a PUT route with metadata.

func Register

func Register(r chi.Router, method, path string, handler http.Handler, meta Meta)

Register registers a route with metadata using an explicit method.

func Trace

func Trace(r chi.Router, path string, handler http.HandlerFunc, meta Meta)

Trace registers a TRACE route with metadata.

func Wrap

func Wrap(handler http.Handler, meta Meta) http.Handler

Wrap attaches metadata to a handler.

Types

type Mapping

type Mapping struct {
	Method         string
	Path           string
	PermissionCode string
}

Mapping represents API to permission code mapping.

type Meta

type Meta struct {
	Description string
	IsPublic    bool
	Permissions []string
}

Meta holds permission codes and route metadata for a handler.

func ExtractMeta

func ExtractMeta(handler http.Handler) (Meta, bool)

ExtractMeta returns metadata from a handler if present.

func Private

func Private(description string, codes ...string) Meta

Private creates metadata for a protected route.

func Public

func Public(description string, codes ...string) Meta

Public creates metadata for a public route.

type MetaHandler

type MetaHandler struct {
	Meta Meta
	// contains filtered or unexported fields
}

MetaHandler wraps a handler with permission metadata.

func (*MetaHandler) ServeHTTP

func (h *MetaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Permission

type Permission struct {
	Code        string
	Name        string
	Description string
	Scope       Scope
	Status      Status
}

Permission represents a permission code definition.

type RouteInfo

type RouteInfo struct {
	Method      string
	Path        string
	Description string
	IsPublic    bool
	Permissions []string
}

RouteInfo represents API route metadata.

type Scope

type Scope string

Scope defines permission scope.

const (
	ScopeAPI  Scope = "api"
	ScopeUI   Scope = "ui"
	ScopeData Scope = "data"
)

type Snapshot

type Snapshot struct {
	Permissions []Permission
	Routes      []RouteInfo
	Mappings    []Mapping
}

Snapshot contains all permissions, routes, and mappings for syncing.

func BuildSnapshot

func BuildSnapshot(routes []RouteInfo) Snapshot

BuildSnapshot builds a deduplicated snapshot from routes.

func SnapshotFromRouter

func SnapshotFromRouter(r chi.Routes) (Snapshot, error)

SnapshotFromRouter walks a chi router and builds a permission snapshot.

type Status

type Status string

Status defines permission status.

const (
	StatusActive     Status = "active"
	StatusDeprecated Status = "deprecated"
)