mod

package module
v0.0.0-...-f4ab9a6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2026 License: Apache-2.0 Imports: 49 Imported by: 0

README

MOD

基于Go Fiber的现代化企业级Web应用框架，专注于快速开发、安全性和可扩展性

Go Version Fiber Version License

📋 目录

✨ 核心特性

🚀 开发效率
  • 服务化架构 - 基于服务注册的模块化开发，推荐使用蛇形命名法（snake_case）
  • 自动API文档 - 内置API文档生成和交互式Web界面
  • 参数验证 - 集成go-playground/validator，支持复杂验证规则
  • 统一响应 - 标准化的JSON响应格式和错误处理
🔒 安全特性
  • JWT认证 - 完整的JWT认证系统，支持角色权限控制和Token管理
  • 服务加解密 - 多级别的加解密配置，支持对称和非对称加密
  • 数字签名 - HMAC-SHA256签名验证，确保数据完整性
  • 白名单机制 - 灵活的服务和分组级白名单配置
🛠 企业功能
  • 多后端日志 - 控制台、文件、Loki、阿里云SLS多种日志输出
  • 文件上传 - 本地、S3、阿里云OSS多后端文件存储
  • 静态文件 - 高性能静态文件服务和目录浏览
  • 缓存系统 - BigCache、BadgerDB、Redis多种缓存方案
🔧 开发工具
  • Mock功能 - 智能Mock数据生成，支持全局、分组、服务级配置
  • 中间件系统 - 丰富的内置中间件和灵活的自定义扩展
  • CORS支持 - 完善的跨域资源共享配置
  • 热重载 - 开发环境友好的配置热加载

🚀 快速开始

安装
go get github.com/iamdanielyin/mod
Hello World
package main

import "github.com/iamdanielyin/mod"

// 定义请求和响应结构
type GetUserRequest struct {
    ID string `json:"id" validate:"required" desc:"用户ID"`
}

type GetUserResponse struct {
    Name  string `json:"name" desc:"用户姓名"`
    Email string `json:"email" desc:"用户邮箱"`
}

func main() {
    app := mod.New()

    // 注册服务（推荐使用蛇形命名法）
    app.Register(mod.Service{
        Name:        "get_user",
        DisplayName: "获取用户信息",
        Description: "根据用户ID获取用户详细信息",
        Handler: mod.MakeHandler(func(ctx *mod.Context, req *GetUserRequest, resp *GetUserResponse) error {
            resp.Name = "张三"
            resp.Email = "zhangsan@example.com"
            return nil
        }),
        Group: "用户管理",
    })

    app.Run(":8080")
}

启动后访问 http://127.0.0.1:8080/services/docs 查看自动生成的API文档。

🏗 核心架构

服务化设计

MOD采用服务化架构，每个业务功能都注册为独立的服务。推荐使用蛇形命名法（snake_case）来命名服务：

app.Register(mod.Service{
    Name:        "get_user",              // 服务名称（推荐蛇形命名）
    DisplayName: "获取用户信息",            // 显示名称
    Description: "根据用户ID获取详细信息",   // 服务描述
    Handler:     mod.MakeHandler(fn),     // 处理函数
    Group:       "用户管理",               // 服务分组
    Sort:        1,                       // 排序
    SkipAuth:    false,                   // 是否跳过认证
    ReturnRaw:   false,                   // 是否返回原始数据
})
中间件系统

MOD提供了丰富的内置中间件，所有全局中间件必须在注册服务之前调用。

中间件概览

MOD支持以下全局中间件：

中间件 功能说明 配置要求
JWT认证中间件 提供JWT令牌认证功能 需要配置 token.jwt 部分
加解密中间件 自动处理请求解密和响应加密 需要配置 encryption 部分
中间件执行顺序
func main() {
    app := mod.New()

    // 推荐的中间件调用顺序
    app.UseEncryption()     // 1. 先处理加解密
    app.UseOptionalJWT()    // 2. 再处理认证

    // 注册服务...
    app.Run(":8080")
}

执行顺序说明：

  • 🔐 加解密中间件 - 首先解密请求数据
  • 🔑 JWT认证中间件 - 然后验证用户身份
  • 📋 服务权限检查 - 最后在服务处理前检查权限
JWT认证中间件

JWT认证中间件提供完整的用户身份认证功能，支持令牌生成、验证、刷新和撤销。

可用方法

MOD提供两种JWT认证模式：

🔒 强制认证模式

app.UseJWT()  // 所有请求必须提供有效JWT令牌

🔓 可选认证模式（推荐）

app.UseOptionalJWT()  // 验证JWT但允许无令牌访问
模式对比
特性 UseJWT() UseOptionalJWT()
缺少令牌时 返回 401 错误 继续执行
令牌无效时 返回 401 错误 继续执行
黑名单令牌 返回 401 错误 返回 401 错误
适用场景 严格认证的API 混合公开/私有接口
推荐用途 企业内部系统 Web应用、移动APP
使用策略

🎯 策略一：灵活控制（推荐）

适用于需要混合公开/私有接口的应用

app.UseOptionalJWT()  // 全局可选认证

// 完全公开的接口
app.Register(mod.Service{
    Name:     "login",
    SkipAuth: true,  // 跳过所有认证检查
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *LoginRequest, resp *LoginResponse) error {
        // 登录逻辑，无需认证
        return nil
    }),
})

// 需要认证的接口
app.Register(mod.Service{
    Name:     "user_info",
    SkipAuth: true,  // 由Handler内部控制
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *UserInfoRequest, resp *UserInfoResponse) error {
        // 手动检查认证状态
        if !ctx.IsAuthenticated() {
            return mod.Reply(401, "需要身份认证")
        }
        // 已认证用户的处理逻辑
        return nil
    }),
})

// 可选认证的接口（个性化功能）
app.Register(mod.Service{
    Name:     "get_articles",
    SkipAuth: true,
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *ArticlesRequest, resp *ArticlesResponse) error {
        if ctx.IsAuthenticated() {
            // 已登录用户看到个性化内容
            resp.Articles = getPersonalizedArticles(ctx.GetUserID())
        } else {
            // 未登录用户看到通用内容
            resp.Articles = getPublicArticles()
        }
        return nil
    }),
})

优势：

  • ✅ 最大灵活性，每个接口精确控制认证逻辑
  • ✅ 支持可选认证场景（个性化功能）
  • ✅ 代码逻辑清晰，容易调试

🔐 策略二：严格认证

适用于大部分接口都需要认证的应用

app.UseJWT()  // 全局强制认证

// 特殊跳过认证的接口
app.Register(mod.Service{
    Name:     "login",
    SkipAuth: true,  // 必须跳过，否则无法登录
    Handler:  mod.MakeHandler(handleLogin),
})

// 自动认证的接口（默认）
app.Register(mod.Service{
    Name:    "user_info",
    // 不设置SkipAuth，框架自动要求JWT认证
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *UserInfoRequest, resp *UserInfoResponse) error {
        // 执行到这里时用户已通过JWT认证
        userID := ctx.GetUserID()    // 保证有值
        username := ctx.GetUsername() // 保证有值
        return nil
    }),
})

优势：

  • ✅ 安全性高，默认所有接口都需要认证
  • ✅ 代码更简洁，减少重复的认证检查
配置示例
# mod.yml
token:
  jwt:
    enabled: true
    secret_key: "your-super-secret-jwt-key"
    issuer: "your-app-name"
    algorithm: "HS256"
    expire_duration: "24h"
    refresh_expire_duration: "168h"

  validation:
    enabled: true
    cache_strategy: "bigcache"
    cache_key_prefix: "jwt:"
上下文方法

JWT中间件会自动解析令牌并将信息注入到上下文中：

// 检查认证状态
if ctx.IsAuthenticated() {
    // 用户已认证
}

// 获取用户信息
userID := ctx.GetUserID()          // 用户ID
username := ctx.GetUsername()      // 用户名
email := ctx.GetUserEmail()        // 邮箱
role := ctx.GetUserRole()          // 角色

// 获取JWT相关信息
token := ctx.GetJWTToken()         // 原始JWT令牌
claims := ctx.GetJWTClaims()       // JWT声明对象
加解密中间件

加解密中间件提供服务级别的数据加解密功能，支持多种加密算法和灵活的配置策略。

启用方法
app.UseEncryption()  // 启用全局加解密中间件
工作原理
  1. 请求处理：自动解密客户端发送的加密数据
  2. 签名验证：验证请求数据的HMAC-SHA256签名
  3. 响应加密：将服务响应数据自动加密后返回
多级配置

加解密中间件支持三级配置，优先级从高到低：

# mod.yml
encryption:
  # 全局级别
  global:
    enabled: true
    algorithm: "AES256-GCM"
    mode: "symmetric"

  # 分组级别
  groups:
    "用户管理":
      enabled: true
      algorithm: "AES256-GCM"

  # 服务级别（优先级最高）
  services:
    "create-user":
      enabled: true
      algorithm: "AES256-GCM"

  # 白名单（跳过加解密）
  whitelist:
    groups:
      - "公开服务"
    services:
      - "login"
      - "register"
使用示例
app.UseEncryption()

// 启用加解密的服务
app.Register(mod.Service{
    Name:        "create_user",
    DisplayName: "创建用户",
    Description: "包含敏感信息，需要加密传输",
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *CreateUserRequest, resp *CreateUserResponse) error {
        // 请求数据已自动解密
        // 响应数据将自动加密
        return nil
    }),
    Group: "用户管理",
})

// 白名单服务（跳过加解密）
app.Register(mod.Service{
    Name:        "login",
    DisplayName: "用户登录",
    Description: "公开接口，无需加密",
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *LoginRequest, resp *LoginResponse) error {
        // 普通的JSON请求/响应
        return nil
    }),
    Group: "公开服务",
})
支持的算法
算法 模式 安全性 性能
AES256-GCM 对称加密 高 快
ChaCha20-Poly1305 对称加密 高 快
RSA-OAEP 非对称加密 很高 慢
配置示例
encryption:
  global:
    enabled: true
    algorithm: "AES256-GCM"
    mode: "symmetric"

  # 对称加密配置
  symmetric:
    algorithm: "AES256-GCM"
    key: "dGhpcy1pcy1hLXN1cGVyLXNlY3JldC1rZXktZm9yLWVuY3J5cHRpb24="

  # 签名验证配置
  signature:
    enabled: true
    algorithm: "HMAC-SHA256"
    key: "dGhpcy1pcy1hLXNpZ25hdHVyZS1rZXktZm9yLXZlcmlmaWNhdGlvbg=="
服务权限系统

MOD提供了基于Token缓存数据的灵活权限控制系统，支持细粒度的权限管理。

权限配置

在服务注册时通过 Permission 字段配置权限规则：

app.Register(mod.Service{
    Name:        "admin_data",
    DisplayName: "管理员数据",
    Handler:     mod.MakeHandler(handleAdminData),
    Permission: &mod.PermissionConfig{
        Rules: []mod.PermissionRule{
            {Field: "user.role", Operator: "eq", Value: "admin"},
        },
        Logic: "AND",
    },
})
权限规则

PermissionRule 结构：

  • Field: Token缓存数据中的字段路径，支持嵌套访问如 "user.role", "permissions.admin"
  • Operator: 操作符，支持 eq、ne、in、not_in、gt、gte、lt、lte、contains、exists
  • Value: 期望值

Logic 类型：

  • "AND": 所有规则都必须满足（默认）
  • "OR": 任一规则满足即可
使用示例
// 管理员专用服务
app.Register(mod.Service{
    Name: "admin_users",
    Permission: &mod.PermissionConfig{
        Rules: []mod.PermissionRule{
            {Field: "user.role", Operator: "eq", Value: "admin"},
        },
    },
})

// VIP服务（需要VIP等级2以上）
app.Register(mod.Service{
    Name: "vip_service",
    Permission: &mod.PermissionConfig{
        Rules: []mod.PermissionRule{
            {Field: "user.vip_level", Operator: "gte", Value: 2},
            {Field: "user.status", Operator: "eq", Value: "active"},
        },
        Logic: "AND",
    },
})

// 多角色服务
app.Register(mod.Service{
    Name: "manager_data",
    Permission: &mod.PermissionConfig{
        Rules: []mod.PermissionRule{
            {Field: "user.role", Operator: "in", Value: []string{"admin", "manager"}},
        },
    },
})
Token缓存数据结构

登录时在Token缓存中存储权限相关数据：

tokenData := map[string]interface{}{
    "user": map[string]interface{}{
        "id":        "123",
        "role":      "admin",
        "vip_level": 3,
        "status":    "active",
    },
    "permissions": map[string]interface{}{
        "user_management": true,
        "financial_data":  false,
    },
    "department": map[string]interface{}{
        "name":  "技术部",
        "level": 4,
    },
}

app.SetToken(accessToken, tokenData)
权限检查流程
  1. 服务请求时自动检查是否配置了 Permission
  2. 如果配置了权限规则，从Token缓存获取用户数据
  3. 根据规则逐一验证字段值
  4. 按照 Logic 类型（AND/OR）综合判断
  5. 权限不足时返回403错误

优势：

  • 灵活性：支持复杂的权限规则组合
  • 实时性：基于Token缓存，支持动态权限更新
  • 无状态：不依赖数据库查询
  • 服务化：完全集成到服务注册流程
上下文增强

提供强大的上下文功能：

func handler(ctx *mod.Context, req *Request, resp *Response) error {
    // 获取用户信息
    userID := ctx.GetUserID()
    claims := ctx.GetJWTClaims()

    // 检查权限
    if !ctx.HasRole("admin") {
        return mod.Reply(403, "权限不足")
    }

    // 结构化日志
    ctx.WithFields(map[string]interface{}{
        "user_id": userID,
        "action":  "update_user",
    }).Info("用户更新操作")

    // 获取应用实例
    config := ctx.App().GetModConfig()

    return nil
}

🔧 功能特性

JWT认证系统

完整的JWT认证系统，使用 github.com/golang-jwt/jwt/v5 库：

核心功能
  • ✅ Token生成和验证
  • 🔐 角色权限控制
  • 🔄 Token刷新机制
  • ❌ Token撤销和黑名单
  • 💾 多种存储后端支持（BigCache、BadgerDB、Redis）
快速开始

1. 配置JWT设置

# mod.yml
token:
  jwt:
    enabled: true
    secret_key: "your-super-secret-jwt-key"
    issuer: "your-app-name"
    algorithm: "HS256"
    expire_duration: "24h"
    refresh_expire_duration: "168h"  # 7天

  validation:
    enabled: true
    cache_strategy: "bigcache"
    cache_key_prefix: "jwt:"

2. 启用JWT中间件

func main() {
    app := mod.New()

    // 选择认证模式（推荐可选模式）
    app.UseOptionalJWT()

    // 注册服务...
    app.Run(":8080")
}
完整用法示例
// 用户登录 - 生成JWT
app.Register(mod.Service{
    Name:     "login",
    SkipAuth: true,  // 登录接口跳过认证
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *LoginRequest, resp *LoginResponse) error {
        // 验证用户名密码...
        user := validateUser(req.Username, req.Password)

        // 生成JWT令牌
        tokens, err := app.GenerateJWT(
            user.ID,
            user.Username,
            user.Email,
            user.Role,
            map[string]interface{}{  // 自定义声明
                "login_time": time.Now().Unix(),
                "permissions": []string{"read", "write"},
            },
        )
        if err != nil {
            return mod.Reply(500, "生成令牌失败")
        }

        // 可选：存储令牌到缓存用于权限控制
        tokenData := map[string]interface{}{
            "user_id": user.ID,
            "role":    user.Role,
            "status":  "active",
        }
        app.SetToken(tokens.AccessToken, tokenData)

        resp.User = user
        resp.Token = tokens
        return nil
    }),
})

// 需要认证的接口
app.Register(mod.Service{
    Name:     "user_info",
    SkipAuth: true,  // 使用内部认证控制
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *UserInfoRequest, resp *UserInfoResponse) error {
        // 检查是否已认证
        if !ctx.IsAuthenticated() {
            return mod.Reply(401, "需要身份认证")
        }

        // 获取用户信息
        userID := ctx.GetUserID()
        username := ctx.GetUsername()
        role := ctx.GetUserRole()

        resp.User = User{
            ID:       userID,
            Username: username,
            Role:     role,
        }
        return nil
    }),
})

// 令牌刷新
app.Register(mod.Service{
    Name:     "refresh",
    SkipAuth: true,
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *RefreshRequest, resp *mod.TokenResponse) error {
        // 刷新令牌
        tokens, err := app.RefreshJWT(req.RefreshToken)
        if err != nil {
            return mod.Reply(401, "刷新令牌无效")
        }

        *resp = *tokens
        return nil
    }),
})

// 用户登出
app.Register(mod.Service{
    Name:     "logout",
    SkipAuth: true,
    Handler: mod.MakeHandler(func(ctx *mod.Context, req *LogoutRequest, resp *LogoutResponse) error {
        token := ctx.GetJWTToken()
        if token == "" {
            return mod.Reply(401, "未提供令牌")
        }

        // 撤销令牌（加入黑名单）
        if err := app.RevokeJWT(token); err != nil {
            return mod.Reply(500, "登出失败")
        }

        // 从缓存移除令牌
        app.RemoveToken(token)

        resp.Message = "登出成功"
        return nil
    }),
})
上下文方法

JWT中间件会自动解析令牌并将信息注入到上下文中：

// 检查认证状态
if ctx.IsAuthenticated() {
    // 用户已认证
}

// 获取用户信息
userID := ctx.GetUserID()          // 用户ID
username := ctx.GetUsername()      // 用户名
email := ctx.GetUserEmail()        // 邮箱
role := ctx.GetUserRole()          // 角色

// 获取JWT相关信息
token := ctx.GetJWTToken()         // 原始JWT令牌
claims := ctx.GetJWTClaims()       // JWT声明对象

// 获取自定义声明
if claims != nil {
    loginTime := claims.ExtraClaims["login_time"]
}
令牌格式支持

MOD支持两种Authorization头格式：

# Bearer格式（标准）
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# 直接格式
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
错误处理
// 令牌验证失败时的错误响应
{
  "code": 401,
  "message": "Invalid authentication token",
  "data": null,
  "timestamp": "2024-01-01T12:00:00Z"
}
服务加解密

多级别的服务加解密系统，保护敏感数据传输：

支持的加密算法
  • 对称加密: AES256-GCM, ChaCha20-Poly1305
  • 非对称加密: RSA-OAEP
  • 数字签名: HMAC-SHA256
配置级别
  • 全局级别: 所有服务默认加密
  • 分组级别: 特定分组的服务加密
  • 服务级别: 特定服务的加密配置
  • 白名单: 跳过加密的服务和分组
配置示例
encryption:
  # 全局配置
  global:
    enabled: true
    algorithm: "AES256-GCM"
    mode: "symmetric"

  # 对称加密配置
  symmetric:
    algorithm: "AES256-GCM"
    key: "base64-encoded-key"
    key_file: "/path/to/key/file"

  # 非对称加密配置
  asymmetric:
    algorithm: "RSA-OAEP"
    public_key: "-----BEGIN PUBLIC KEY-----..."
    private_key: "-----BEGIN PRIVATE KEY-----..."
    key_size: 2048

  # 签名验证配置
  signature:
    enabled: true
    algorithm: "HMAC-SHA256"
    key: "signature-key"

  # 分组级别配置
  groups:
    "敏感数据":
      enabled: true

  # 服务级别配置
  services:
    "get_user_detail":
      enabled: true

  # 白名单配置
  whitelist:
    groups: ["公开数据"]
    services: ["health_check"]
使用方式
// 启用加解密中间件
app.UseEncryption()

// 手动加解密
encrypted, err := app.EncryptData(data, "symmetric")
decrypted, err := app.DecryptData(encrypted, "symmetric")

// 数字签名
signature, err := app.SignData(data)
err = app.VerifySignature(data, signature)
文件服务
文件上传

支持多种存储后端的文件上传：

file_upload:
  # 本地存储
  local:
    enabled: true
    upload_dir: "./uploads"
    max_size: "50MB"
    allowed_types: ["image/jpeg", "image/png", "application/pdf"]
    allowed_exts: [".jpg", ".png", ".pdf"]
    keep_original_name: false
    auto_create_dir: true
    date_sub_dir: true

  # AWS S3
  s3:
    enabled: true
    bucket: "my-bucket"
    region: "us-east-1"
    access_key: "your-access-key"
    secret_key: "your-secret-key"

  # 阿里云OSS
  oss:
    enabled: true
    bucket: "my-oss-bucket"
    endpoint: "oss-cn-shenzhen.aliyuncs.com"
    access_key_id: "your-access-key-id"
    access_key_secret: "your-access-key-secret"
静态文件

高性能静态文件服务：

static_mounts:
  - url_prefix: "/static"
    local_path: "./static"
    browseable: true
    index_file: "index.html"

  - url_prefix: "/docs"
    local_path: "./docs"
    browseable: false
    index_file: "README.html"
日志系统
多后端日志支持
logging:
  # 控制台日志
  console:
    enabled: true
    level: "info"

  # 文件日志（支持轮转）
  file:
    enabled: true
    path: "./logs/app.log"
    max_size: "100MB"
    max_backups: 10
    max_age: "30d"
    compress: true

  # Grafana Loki
  loki:
    enabled: true
    url: "http://127.0.0.1:3100/loki/api/v1/push"
    labels:
      service: "mod-app"
      environment: "production"
    batch_size: 100
    timeout: "10s"

  # 阿里云SLS
  sls:
    enabled: true
    endpoint: "cn-shenzhen.log.aliyuncs.com"
    project: "my-project"
    logstore: "my-logstore"
    access_key_id: "your-access-key-id"
    access_key_secret: "your-access-key-secret"
结构化日志
// 基础日志
ctx.Info("用户登录成功")

// 结构化日志
ctx.WithFields(map[string]interface{}{
    "user_id": "123",
    "action":  "login",
    "ip":      "192.168.1.1",
}).Info("用户登录成功")

// 获取Logger实例
logger := ctx.Logger()
logger.WithField("key", "value").Warn("警告信息")
Mock功能

智能Mock数据生成，支持多级别配置：

mock:
  # 全局Mock
  global:
    enabled: false

  # 分组Mock
  groups:
    "用户管理":
      enabled: true

  # 服务Mock
  services:
    "get_user":
      enabled: true

Mock功能会根据响应结构自动生成合理的测试数据，支持开发和测试阶段快速原型开发。

缓存系统

用于JWT Token验证的多种缓存方案：

cache:
  # BigCache（内存缓存）
  bigcache:
    enabled: true
    shards: 1024
    life_window: "24h"
    clean_window: "1h"
    max_entries_in_window: 10000
    max_entry_size: 1024

  # BadgerDB（持久化缓存）
  badger:
    enabled: false
    path: "./data/tokens"
    in_memory: false
    sync_writes: false
    ttl: "24h"

  # Redis
  redis:
    enabled: false
    address: "127.0.0.1:6379"
    password: ""
    db: 0
    pool_size: 10
    min_idle_conns: 0
    ttl: "24h"

⚙️ 配置系统

MOD使用YAML配置文件 mod.yml 进行统一配置管理。配置文件支持环境变量替换和热重载。

完整配置示例
# 应用配置
app:
  name: "MyApp"
  display_name: "我的应用"
  description: "应用描述"
  version: "1.0.0"
  service_base: "/services"
  token_keys: ["Authorization", "X-API-Key", "mod-token"]

# 服务器配置
server:
  host: "127.0.0.1"
  port: 8080
  read_timeout: "30s"
  write_timeout: "30s"
  idle_timeout: "120s"
  body_limit: "100MB"
  concurrency: 256

  # CORS配置
  cors:
    enabled: true
    allow_origins: ["*"]
    allow_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allow_headers: ["Origin", "Content-Type", "Accept", "Authorization"]
    allow_credentials: false
    max_age: "24h"

📚 完整示例

MOD提供了丰富的示例，涵盖所有核心功能：

examples/
├── basic-services/     # 基础服务注册和参数验证
├── jwt-auth/          # JWT认证和权限控制
├── encryption/        # 服务加解密和签名验证
├── file-upload/       # 多后端文件上传
├── static-files/      # 静态文件服务
├── logging/           # 多种日志输出方式
└── mock/              # 服务Mock功能

每个示例都可以独立运行：

cd examples/basic-services
go run main.go

📖 配置参考

应用配置 (app)
配置项 类型 说明 默认值
name string 应用名称 "MOD"
display_name string 应用显示名称 "MOD Application"
description string 应用描述 ""
version string 应用版本 ""
service_base string 服务基础路径 "/services"
token_keys []string Token请求头名称 ["Authorization", "X-API-Key", "mod-token"]
服务器配置 (server)
配置项 类型 说明 默认值
host string 监听主机 ""
port int 监听端口 8080
read_timeout string 读取超时 "30s"
write_timeout string 写入超时 "30s"
idle_timeout string 空闲超时 "120s"
body_limit string 请求体大小限制 "100MB"
concurrency int 并发连接数 256
CORS配置 (server.cors)
配置项 类型 说明 默认值
enabled bool 是否启用CORS false
allow_origins []string 允许的源 ["*"]
allow_methods []string 允许的HTTP方法 ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
allow_headers []string 允许的请求头 ["Origin", "Content-Type", "Accept", "Authorization"]
allow_credentials bool 是否允许携带凭证 false
max_age string 预检请求缓存时间 "24h"
JWT配置 (jwt)
配置项 类型 说明 默认值
enabled bool 是否启用JWT false
secret_key string JWT签名密钥 ""
issuer string JWT签发者 ""
expire_duration string Access Token过期时间 "24h"
refresh_expire_duration string Refresh Token过期时间 "168h"
algorithm string 签名算法 "HS256"
加解密配置 (encryption)
全局配置 (encryption.global)
配置项 类型 说明 默认值
enabled bool 是否启用全局加解密 false
algorithm string 加密算法 "AES256-GCM"
mode string 加密模式 (symmetric/asymmetric) "symmetric"
对称加密配置 (encryption.symmetric)
配置项 类型 说明 默认值
algorithm string 对称加密算法 "AES256-GCM"
key string 加密密钥 (base64编码) ""
key_file string 密钥文件路径 ""
非对称加密配置 (encryption.asymmetric)
配置项 类型 说明 默认值
algorithm string 非对称加密算法 "RSA-OAEP"
public_key string 公钥内容 (PEM格式) ""
private_key string 私钥内容 (PEM格式) ""
public_key_file string 公钥文件路径 ""
private_key_file string 私钥文件路径 ""
key_size int RSA密钥长度 2048
签名验证配置 (encryption.signature)
配置项 类型 说明 默认值
enabled bool 是否启用签名验证 false
algorithm string 签名算法 "HMAC-SHA256"
key string 签名密钥 ""
key_file string 签名密钥文件路径 ""
日志配置 (logging)
控制台日志 (logging.console)
配置项 类型 说明 默认值
enabled bool 是否启用控制台日志 true
level string 日志级别 (debug/info/warn/error) "info"
文件日志 (logging.file)
配置项 类型 说明 默认值
enabled bool 是否启用文件日志 false
path string 日志文件路径 ""
max_size string 单个日志文件最大大小 "100MB"
max_backups int 保留的历史日志文件数量 3
max_age string 日志文件保留时间 "30d"
compress bool 是否压缩历史日志文件 false
文件上传配置 (file_upload)
本地上传配置 (file_upload.local)
配置项 类型 说明 默认值
enabled bool 是否启用本地文件上传 false
upload_dir string 上传目录路径 "./uploads"
max_size string 单文件最大大小 "10MB"
allowed_types []string 允许的文件MIME类型 []
allowed_exts []string 允许的文件扩展名 []
keep_original_name bool 是否保持原始文件名 false
auto_create_dir bool 自动创建上传目录 true
date_sub_dir bool 按日期创建子目录 false
缓存配置 (cache)
BigCache配置 (cache.bigcache)
配置项 类型 说明 默认值
enabled bool 是否启用BigCache false
shards int 分片数量 1024
life_window string 生命周期窗口 "24h"
clean_window string 清理窗口 "1h"
max_entries_in_window int 窗口内最大条目数 10000
max_entry_size int 最大条目大小 1024

🆘 获取帮助

📄 许可证

本项目采用 Apache 2.0 许可证。

📖 文档说明

这是MOD的唯一完整文档，包含了所有功能特性的详细说明和配置参考。

MOD - 让Go Web开发更简单、更安全、更高效！

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckEncryption 

func CheckEncryption(config *ModConfig, serviceName, groupName string) bool

CheckEncryption 检查是否需要加密

func CheckPassword 

func CheckPassword(inputPassword, targetPassword string) bool

func DecodeURIComponent 

func DecodeURIComponent(str string) string

func EncodeURIComponent 

func EncodeURIComponent(str string) string

func EncryptionMiddleware 

func EncryptionMiddleware(app *App) fiber.Handler

EncryptionMiddleware 加解密中间件

func GenPassword 

func GenPassword(inputPassword string) (string, error)

func JSONParse 

func JSONParse(s string, v any) error

func JSONStringify 

func JSONStringify(v any, format ...bool) string

func JWTMiddleware 

func JWTMiddleware(app *App) fiber.Handler

JWTMiddleware creates a JWT authentication middleware

func MD5Str 

func MD5Str(str string) string

func NewRandomNumber 

func NewRandomNumber(length int) string

func NewUUID 

func NewUUID(upper bool, hyphen bool) string

func NewUUIDToken 

func NewUUIDToken() string

func NextSnowflakeID 

func NextSnowflakeID() snowflake.ID

func NextSnowflakeIntID 

func NextSnowflakeIntID() int64

func NextSnowflakeStringID 

func NextSnowflakeStringID() string

func OptionalJWTMiddleware 

func OptionalJWTMiddleware(app *App) fiber.Handler

OptionalJWTMiddleware creates an optional JWT authentication middleware It validates JWT if present but doesn't fail if missing

func Reply 

func Reply(code int, msg string) error

func ReplyWithDetail 

func ReplyWithDetail(code int, msg, detail string) error

func RoleMiddleware 

func RoleMiddleware(requiredRoles ...string) fiber.Handler

RoleMiddleware creates a role-based authorization middleware

func SplitAndTrimSpace 

func SplitAndTrimSpace(s, sep string) []string

Types

type ApiResponse 

type ApiResponse struct {
	Code   int    `json:"code"`
	Data   any    `json:"data,omitempty"`
	Msg    string `json:"msg"`
	Detail string `json:"detail,omitempty"`
	Rid    string `json:"rid"`
}

统一响应格式

func NewErrorResponse 

func NewErrorResponse(ctx *Context, code int, msg string, detail ...string) *ApiResponse

生成错误响应

func NewSuccessResponse 

func NewSuccessResponse(ctx *Context, data any) *ApiResponse

生成成功响应

type App 

type App struct {
	*fiber.App
	// contains filtered or unexported fields
}

func New 

func New(config ...Config) *App

func (*App) CheckServicePermission 

func (app *App) CheckServicePermission(token string, permission *PermissionConfig) bool

CheckServicePermission 检查服务权限

func (*App) Close 

func (app *App) Close() error

Close 关闭应用时释放资源

func (*App) Debug 

func (app *App) Debug(args ...any)

Logger methods for App

func (*App) Debugf 

func (app *App) Debugf(format string, args ...any)

func (*App) DecryptData 

func (app *App) DecryptData(data []byte, mode string) ([]byte, error)

DecryptData decrypts data using the configured symmetric or asymmetric algorithm

func (*App) EncryptData 

func (app *App) EncryptData(data []byte, mode string) ([]byte, error)

EncryptData encrypts data using the configured symmetric or asymmetric algorithm

func (*App) Error 

func (app *App) Error(args ...any)

func (*App) Errorf 

func (app *App) Errorf(format string, args ...any)

func (*App) GenerateJWT 

func (app *App) GenerateJWT(userID, username, email, role string, extra map[string]any) (*TokenResponse, error)

GenerateJWT generates JWT tokens for a user

func (*App) GetJWTManager 

func (app *App) GetJWTManager() *JWTManager

GetJWTManager returns the JWT manager for the app

func (*App) GetLogger 

func (app *App) GetLogger() *logrus.Logger

GetLogger returns the logger instance

func (*App) GetModConfig 

func (app *App) GetModConfig() *ModConfig

GetModConfig returns the loaded mod.yml configuration Returns nil if no mod.yml was loaded

func (*App) GetTokenData 

func (app *App) GetTokenData(token string) ([]byte, error)

GetTokenData 从缓存中获取 token 相关的数据 这个方法可以用来获取存储在 token 中的用户信息等数据

func (*App) Info 

func (app *App) Info(args ...any)

func (*App) Infof 

func (app *App) Infof(format string, args ...any)

func (*App) Logger 

func (app *App) Logger() *logrus.Logger

Logger returns the logger instance (alias for GetLogger)

func (*App) RefreshJWT 

func (app *App) RefreshJWT(refreshToken string) (*TokenResponse, error)

RefreshJWT refreshes a JWT token using refresh token

func (*App) Register 

func (app *App) Register(svc Service) error

func (*App) RemoveToken 

func (app *App) RemoveToken(token string) error

RemoveToken 从缓存中删除 token 这个方法可以在用户登出时调用，使 token 失效

func (*App) RevokeJWT 

func (app *App) RevokeJWT(tokenString string) error

RevokeJWT revokes a JWT token

func (*App) Run 

func (app *App) Run(addr ...string)

func (*App) SetToken 

func (app *App) SetToken(token string, data any) error

SetToken 将 token 添加到缓存中 这个方法可以在用户登录时调用，将有效的 token 存储到缓存中

func (*App) SignData 

func (app *App) SignData(data []byte) ([]byte, error)

SignData creates a digital signature for the given data

func (*App) UseEncryption 

func (app *App) UseEncryption()

UseEncryption enables encryption middleware for all routes

func (*App) UseJWT 

func (app *App) UseJWT()

UseJWT enables JWT middleware for all routes

func (*App) UseOptionalJWT 

func (app *App) UseOptionalJWT()

UseOptionalJWT enables optional JWT middleware for all routes

func (*App) ValidateJWT 

func (app *App) ValidateJWT(tokenString string) (*JWTClaims, error)

ValidateJWT validates a JWT token

func (*App) VerifySignature 

func (app *App) VerifySignature(data, signature []byte) error

VerifySignature verifies a digital signature for the given data

func (*App) Warn 

func (app *App) Warn(args ...any)

func (*App) Warnf 

func (app *App) Warnf(format string, args ...any)

func (*App) WithError 

func (app *App) WithError(err error) *logrus.Entry

func (*App) WithField 

func (app *App) WithField(key string, value any) *logrus.Entry

func (*App) WithFields 

func (app *App) WithFields(fields logrus.Fields) *logrus.Entry

type AsymmetricEncryption 

type AsymmetricEncryption struct {
	Algorithm  string
	PublicKey  *rsa.PublicKey
	PrivateKey *rsa.PrivateKey
}

AsymmetricEncryption 非对称加密

func NewAsymmetricEncryption 

func NewAsymmetricEncryption(config *ModConfig) (*AsymmetricEncryption, error)

NewAsymmetricEncryption 创建非对称加密实例

func (*AsymmetricEncryption) Decrypt 

func (a *AsymmetricEncryption) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt 非对称解密（使用私钥）

func (*AsymmetricEncryption) Encrypt 

func (a *AsymmetricEncryption) Encrypt(plaintext []byte) ([]byte, error)

Encrypt 非对称加密（使用公钥）

type Config 

type Config struct {
	fiber.Config
	Logger *logrus.Logger

	// ModConfig holds the complete configuration from mod.yml
	ModConfig *ModConfig `json:"-"`
}

type Context 

type Context struct {
	*fiber.Ctx
	RequestID string
	// contains filtered or unexported fields
}

func (*Context) App 

func (c *Context) App() *App

App returns the App instance

func (*Context) Debug 

func (c *Context) Debug(args ...any)

Logger methods with automatic rid inclusion

func (*Context) Debugf 

func (c *Context) Debugf(format string, args ...any)

func (*Context) Error 

func (c *Context) Error(args ...any)

func (*Context) Errorf 

func (c *Context) Errorf(format string, args ...any)

func (*Context) GetJWTClaims 

func (c *Context) GetJWTClaims() *JWTClaims

GetJWTClaims returns the JWT claims from the context

func (*Context) GetJWTToken 

func (c *Context) GetJWTToken() string

GetJWTToken returns the JWT token string from the context

func (*Context) GetLogger 

func (c *Context) GetLogger() *logrus.Logger

GetLogger returns the logger instance

func (*Context) GetRequestID 

func (c *Context) GetRequestID() string

func (*Context) GetUserEmail 

func (c *Context) GetUserEmail() string

GetUserEmail returns the user email from JWT claims

func (*Context) GetUserID 

func (c *Context) GetUserID() string

GetUserID returns the user ID from JWT claims

func (*Context) GetUserRole 

func (c *Context) GetUserRole() string

GetUserRole returns the user role from JWT claims

func (*Context) GetUsername 

func (c *Context) GetUsername() string

GetUsername returns the username from JWT claims

func (*Context) HasAnyRole 

func (c *Context) HasAnyRole(roles ...string) bool

HasAnyRole checks if the current user has any of the specified roles

func (*Context) HasRole 

func (c *Context) HasRole(role string) bool

HasRole checks if the current user has the specified role

func (*Context) Info 

func (c *Context) Info(args ...any)

func (*Context) Infof 

func (c *Context) Infof(format string, args ...any)

func (*Context) IsAuthenticated 

func (c *Context) IsAuthenticated() bool

IsAuthenticated checks if the request has valid JWT authentication

func (*Context) Logger 

func (c *Context) Logger() *logrus.Logger

Logger returns the logger instance (alias for GetLogger)

func (*Context) Warn 

func (c *Context) Warn(args ...any)

func (*Context) Warnf 

func (c *Context) Warnf(format string, args ...any)

func (*Context) WithFields 

func (c *Context) WithFields(fields logrus.Fields) *logrus.Entry

type DocData 

type DocData struct {
	AppInfo struct {
		Name        string
		DisplayName string
		Description string
		Version     string
	}
	Groups []DocGroup
}

DocData contains all documentation data including app info and service groups

type DocField 

type DocField struct {
	Name          string
	Type          string
	Description   string
	Required      bool
	From          string // query, header, form, param
	Tag           string
	Level         int        // 嵌套层级，0为顶层
	Parent        string     // 父字段名
	Children      []DocField // 子字段（用于对象类型）
	IsObject      bool       // 是否为对象类型
	IsArray       bool       // 是否为数组类型
	ArrayItemType string     // 数组元素类型
}

文档生成相关结构体

type DocGroup 

type DocGroup struct {
	Name     string
	Services []DocService
}

type DocService 

type DocService struct {
	Service
	ServicePath  string
	InputFields  []DocField
	OutputFields []DocField
}

type EncryptedRequest 

type EncryptedRequest struct {
	Data      string `json:"data"`      // Base64编码的加密数据
	Signature string `json:"signature"` // Base64编码的签名
	Mode      string `json:"mode"`      // 加密模式: symmetric/asymmetric
}

EncryptedRequest 加密的请求格式

type EncryptedResponse 

type EncryptedResponse struct {
	Data      string `json:"data"`      // Base64编码的加密数据
	Signature string `json:"signature"` // Base64编码的签名
	Mode      string `json:"mode"`      // 加密模式: symmetric/asymmetric
}

EncryptedResponse 加密的响应格式

type EncryptionManager 

type EncryptionManager struct {
	// contains filtered or unexported fields
}

EncryptionManager 加解密管理器

func NewEncryptionManager 

func NewEncryptionManager(config *ModConfig) *EncryptionManager

NewEncryptionManager 创建加解密管理器

type Handler 

type Handler struct {
	Func       func(ctx *Context, args, reply any) error
	InputType  reflect.Type
	OutputType reflect.Type
}

Handler 结构体，可以存储类型信息

func MakeHandler 

func MakeHandler[I any, O any](handler func(ctx *Context, args *I, reply *O) error) Handler

MakeHandler 创建带类型信息的 Handler

type JWTClaims 

type JWTClaims struct {
	UserID   string         `json:"user_id"`
	Username string         `json:"username"`
	Email    string         `json:"email"`
	Role     string         `json:"role"`
	Extra    map[string]any `json:"extra,omitempty"`
	jwt.RegisteredClaims
}

JWTClaims represents the JWT claims structure

type JWTManager 

type JWTManager struct {
	// contains filtered or unexported fields
}

JWTManager manages JWT token operations

func NewJWTManager 

func NewJWTManager(app *App) *JWTManager

NewJWTManager creates a new JWT manager instance

func (*JWTManager) ExtractTokenFromRequest 

func (j *JWTManager) ExtractTokenFromRequest(ctx *Context) string

ExtractTokenFromRequest extracts JWT token from HTTP request

func (*JWTManager) GenerateTokens 

func (j *JWTManager) GenerateTokens(userID, username, email, role string, extra map[string]any) (*TokenResponse, error)

GenerateTokens generates both access and refresh tokens

func (*JWTManager) IsEnabled 

func (j *JWTManager) IsEnabled() bool

IsEnabled checks if JWT is enabled in configuration

func (*JWTManager) IsTokenBlacklisted 

func (j *JWTManager) IsTokenBlacklisted(tokenString string) bool

IsTokenBlacklisted checks if a token is in the blacklist

func (*JWTManager) RefreshToken 

func (j *JWTManager) RefreshToken(refreshTokenString string) (*TokenResponse, error)

RefreshToken refreshes an access token using a refresh token

func (*JWTManager) RevokeToken 

func (j *JWTManager) RevokeToken(tokenString string) error

RevokeToken revokes a token by adding it to the cache blacklist

func (*JWTManager) ValidateToken 

func (j *JWTManager) ValidateToken(tokenString string) (*JWTClaims, error)

ValidateToken validates a JWT token and returns the claims

type MockGenerator 

type MockGenerator struct {
	// contains filtered or unexported fields
}

MockGenerator 负责根据结构体定义生成Mock数据

func NewMockGenerator 

func NewMockGenerator() *MockGenerator

NewMockGenerator 创建一个新的Mock数据生成器

func (*MockGenerator) GenerateMockData 

func (m *MockGenerator) GenerateMockData(t reflect.Type) any

GenerateMockData 根据类型生成Mock数据

type ModConfig 

type ModConfig struct {
	App struct {
		// 应用基础信息
		Name        string   `yaml:"name"`
		DisplayName string   `yaml:"display_name"`
		Description string   `yaml:"description"`
		Version     string   `yaml:"version"`
		ServiceBase string   `yaml:"service_base"`
		TokenKeys   []string `yaml:"token_keys"`
	} `yaml:"app"`

	// 服务器配置 - 从app中拆分出来的独立配置
	Server struct {
		Host                      string   `yaml:"host"`
		Port                      int      `yaml:"port"`
		ReadTimeout               string   `yaml:"read_timeout"`
		WriteTimeout              string   `yaml:"write_timeout"`
		IdleTimeout               string   `yaml:"idle_timeout"`
		ReadBufferSize            int      `yaml:"read_buffer_size"`
		WriteBufferSize           int      `yaml:"write_buffer_size"`
		CompressedFileSuffix      string   `yaml:"compressed_file_suffix"`
		ProxyHeader               string   `yaml:"proxy_header"`
		GETOnly                   bool     `yaml:"get_only"`
		DisableKeepalive          bool     `yaml:"disable_keepalive"`
		DisableDefaultDate        bool     `yaml:"disable_default_date"`
		DisableDefaultContentType bool     `yaml:"disable_default_content_type"`
		DisableHeaderNormalizing  bool     `yaml:"disable_header_normalizing"`
		DisableStartupMessage     bool     `yaml:"disable_startup_message"`
		EnableTrustedProxyCheck   bool     `yaml:"enable_trusted_proxy_check"`
		Prefork                   bool     `yaml:"prefork"`
		StrictRouting             bool     `yaml:"strict_routing"`
		CaseSensitive             bool     `yaml:"case_sensitive"`
		UnescapePath              bool     `yaml:"unescape_path"`
		ETag                      bool     `yaml:"etag"`
		BodyLimit                 string   `yaml:"body_limit"`
		Concurrency               int      `yaml:"concurrency"`
		Views                     string   `yaml:"views"`
		TrustedProxies            []string `yaml:"trusted_proxies"`

		// CORS跨域配置
		CORS struct {
			Enabled          bool     `yaml:"enabled"`           // 是否启用CORS
			AllowOrigins     []string `yaml:"allow_origins"`     // 允许的源
			AllowMethods     []string `yaml:"allow_methods"`     // 允许的HTTP方法
			AllowHeaders     []string `yaml:"allow_headers"`     // 允许的请求头
			AllowCredentials bool     `yaml:"allow_credentials"` // 是否允许携带凭证
			ExposeHeaders    []string `yaml:"expose_headers"`    // 暴露的响应头
			MaxAge           string   `yaml:"max_age"`           // 预检请求缓存时间
		} `yaml:"cors"`
	} `yaml:"server"`

	Cache struct {
		BigCache struct {
			Enabled            bool   `yaml:"enabled"`
			Shards             int    `yaml:"shards"`
			LifeWindow         string `yaml:"life_window"`
			CleanWindow        string `yaml:"clean_window"`
			MaxEntriesInWindow int    `yaml:"max_entries_in_window"`
			MaxEntrySize       int    `yaml:"max_entry_size"`
			Verbose            bool   `yaml:"verbose"`
			HardMaxCacheSize   int    `yaml:"hard_max_cache_size"`
		} `yaml:"bigcache"`

		Badger struct {
			Enabled                 bool   `yaml:"enabled"`
			Path                    string `yaml:"path"`
			InMemory                bool   `yaml:"in_memory"`
			SyncWrites              bool   `yaml:"sync_writes"`
			ValueLogFileSize        int    `yaml:"value_log_file_size"`
			NumCompactors           int    `yaml:"num_compactors"`
			NumLevelZeroTables      int    `yaml:"num_level_zero_tables"`
			NumLevelZeroTablesStall int    `yaml:"num_level_zero_tables_stall"`
			ValueLogLoadSize        int    `yaml:"value_log_load_size"`
			TTL                     string `yaml:"ttl"` // Token 过期时间
		} `yaml:"badger"`

		Redis struct {
			Enabled      bool   `yaml:"enabled"`
			Address      string `yaml:"address"`
			Password     string `yaml:"password"`
			DB           int    `yaml:"db"`
			PoolSize     int    `yaml:"pool_size"`
			MinIdleConns int    `yaml:"min_idle_conns"`
			DialTimeout  string `yaml:"dial_timeout"`
			ReadTimeout  string `yaml:"read_timeout"`
			WriteTimeout string `yaml:"write_timeout"`
			IdleTimeout  string `yaml:"idle_timeout"`
			MaxConnAge   string `yaml:"max_conn_age"`
			TTL          string `yaml:"ttl"` // Token 过期时间
		} `yaml:"redis"`
	} `yaml:"cache"`

	RSAKeys struct {
		PrivateKey string `yaml:"private_key"`
		PublicKey  string `yaml:"public_key"`
	} `yaml:"rsa_keys"`

	FileUpload struct {
		Local struct {
			Enabled          bool     `yaml:"enabled"`            // 是否启用本地文件上传
			UploadDir        string   `yaml:"upload_dir"`         // 上传目录路径
			MaxSize          string   `yaml:"max_size"`           // 单文件最大大小
			AllowedTypes     []string `yaml:"allowed_types"`      // 允许的文件MIME类型
			AllowedExts      []string `yaml:"allowed_exts"`       // 允许的文件扩展名
			KeepOriginalName bool     `yaml:"keep_original_name"` // 是否保持原始文件名
			AutoCreateDir    bool     `yaml:"auto_create_dir"`    // 自动创建上传目录
			DateSubDir       bool     `yaml:"date_sub_dir"`       // 按日期创建子目录
		} `yaml:"local"`

		S3 struct {
			Enabled   bool   `yaml:"enabled"`
			Bucket    string `yaml:"bucket"`
			Region    string `yaml:"region"`
			AccessKey string `yaml:"access_key"`
			SecretKey string `yaml:"secret_key"`
			Endpoint  string `yaml:"endpoint"`
		} `yaml:"s3"`

		OSS struct {
			Enabled         bool   `yaml:"enabled"`
			Bucket          string `yaml:"bucket"`
			Endpoint        string `yaml:"endpoint"`
			AccessKeyID     string `yaml:"access_key_id"`
			AccessKeySecret string `yaml:"access_key_secret"`
		} `yaml:"oss"`
	} `yaml:"file_upload"`

	StaticMounts []struct {
		URLPrefix  string `yaml:"url_prefix"`
		LocalPath  string `yaml:"local_path"`
		Browseable bool   `yaml:"browseable"`
		IndexFile  string `yaml:"index_file"`
	} `yaml:"static_mounts"`

	Logging struct {
		Console struct {
			Enabled bool   `yaml:"enabled"`
			Level   string `yaml:"level"`
		} `yaml:"console"`

		Loki struct {
			Enabled   bool              `yaml:"enabled"`
			URL       string            `yaml:"url"`
			Labels    map[string]string `yaml:"labels"`
			BatchSize int               `yaml:"batch_size"`
			Timeout   string            `yaml:"timeout"`
		} `yaml:"loki"`

		SLS struct {
			Enabled         bool   `yaml:"enabled"`
			Endpoint        string `yaml:"endpoint"`
			Project         string `yaml:"project"`
			Logstore        string `yaml:"logstore"`
			AccessKeyID     string `yaml:"access_key_id"`
			AccessKeySecret string `yaml:"access_key_secret"`
		} `yaml:"sls"`

		File struct {
			Enabled    bool   `yaml:"enabled"`
			Path       string `yaml:"path"`
			MaxSize    string `yaml:"max_size"`
			MaxBackups int    `yaml:"max_backups"`
			MaxAge     string `yaml:"max_age"`
			Compress   bool   `yaml:"compress"`
		} `yaml:"file"`
	} `yaml:"logging"`

	Token struct {
		JWT struct {
			Enabled               bool   `yaml:"enabled"`
			SecretKey             string `yaml:"secret_key"`
			Issuer                string `yaml:"issuer"`
			ExpireDuration        string `yaml:"expire_duration"`
			RefreshExpireDuration string `yaml:"refresh_expire_duration"`
			Algorithm             string `yaml:"algorithm"`
		} `yaml:"jwt"`

		Validation struct {
			Enabled          bool   `yaml:"enabled"`
			SkipExpiredCheck bool   `yaml:"skip_expired_check"`
			CacheStrategy    string `yaml:"cache_strategy"` // "bigcache", "badger", "redis"
			CacheKeyPrefix   string `yaml:"cache_key_prefix"`
		} `yaml:"validation"`
	} `yaml:"token"`

	// 服务加解密配置 - 支持三个级别的加解密设置
	Encryption struct {
		// 全局加解密设置
		Global struct {
			Enabled   bool   `yaml:"enabled"`   // 是否启用全局加解密
			Algorithm string `yaml:"algorithm"` // 加密算法: AES256-GCM, RSA-OAEP, ChaCha20-Poly1305
			Mode      string `yaml:"mode"`      // 加密模式: symmetric, asymmetric
		} `yaml:"global"`

		// 对称加密配置
		Symmetric struct {
			Algorithm string `yaml:"algorithm"` // AES256-GCM, ChaCha20-Poly1305
			Key       string `yaml:"key"`       // 加密密钥 (base64编码)
			KeyFile   string `yaml:"key_file"`  // 密钥文件路径
		} `yaml:"symmetric"`

		// 非对称加密配置
		Asymmetric struct {
			Algorithm      string `yaml:"algorithm"`        // RSA-OAEP, ECDH
			PublicKey      string `yaml:"public_key"`       // 公钥内容 (PEM格式)
			PrivateKey     string `yaml:"private_key"`      // 私钥内容 (PEM格式)
			PublicKeyFile  string `yaml:"public_key_file"`  // 公钥文件路径
			PrivateKeyFile string `yaml:"private_key_file"` // 私钥文件路径
			KeySize        int    `yaml:"key_size"`         // RSA密钥长度 (2048, 3072, 4096)
		} `yaml:"asymmetric"`

		// 签名验证配置
		Signature struct {
			Enabled   bool   `yaml:"enabled"`   // 是否启用签名验证
			Algorithm string `yaml:"algorithm"` // 签名算法: HMAC-SHA256, RSA-PSS, ECDSA
			Key       string `yaml:"key"`       // 签名密钥
			KeyFile   string `yaml:"key_file"`  // 签名密钥文件路径
		} `yaml:"signature"`

		// 分组级别加解密设置
		Groups map[string]struct {
			Enabled   bool   `yaml:"enabled"`   // 是否启用该分组的加解密
			Algorithm string `yaml:"algorithm"` // 覆盖全局算法设置
			Mode      string `yaml:"mode"`      // 覆盖全局模式设置
		} `yaml:"groups"`

		// 服务级别加解密设置
		Services map[string]struct {
			Enabled   bool   `yaml:"enabled"`   // 是否启用该服务的加解密
			Algorithm string `yaml:"algorithm"` // 覆盖全局算法设置
			Mode      string `yaml:"mode"`      // 覆盖全局模式设置
		} `yaml:"services"`

		// 白名单服务 - 跳过加解密验证
		Whitelist struct {
			Groups   []string `yaml:"groups"`   // 白名单分组
			Services []string `yaml:"services"` // 白名单服务
		} `yaml:"whitelist"`
	} `yaml:"encryption"`

	// Mock配置 - 支持三个级别的Mock设置
	Mock struct {
		// 全局Mock设置
		Global struct {
			Enabled bool `yaml:"enabled"` // 是否启用全局Mock
		} `yaml:"global"`

		// 分组级别Mock设置
		Groups map[string]struct {
			Enabled bool `yaml:"enabled"` // 是否启用该分组的Mock
		} `yaml:"groups"`

		// 服务级别Mock设置
		Services map[string]struct {
			Enabled bool `yaml:"enabled"` // 是否启用该服务的Mock
		} `yaml:"services"`
	} `yaml:"mock"`
}

ModConfig represents the structure of mod.yml configuration file

type PermissionConfig 

type PermissionConfig struct {
	// 权限规则列表，支持AND/OR逻辑
	Rules []PermissionRule `json:"rules"`
	// 规则之间的逻辑关系：AND（默认）或 OR
	Logic string `json:"logic"` // "AND" | "OR"
}

PermissionConfig 权限配置

type PermissionRule 

type PermissionRule struct {
	// Token缓存数据中的字段路径，如 "user.role", "permissions.admin", "department.level"
	Field string `json:"field"`
	// 操作符：eq, ne, in, not_in, gt, gte, lt, lte, contains, exists
	Operator string `json:"operator"`
	// 期望值
	Value any `json:"value"`
}

PermissionRule 权限规则

type Service 

type Service struct {
	Name        string  `validate:"required"`
	DisplayName string  `validate:"required"`
	Handler     Handler `validate:"required"`

	Description string
	SkipAuth    bool
	ReturnRaw   bool
	Group       string // 在文档中的分组
	Sort        int    // 在文档中的排序值，从小到大排列

	// 权限控制配置
	Permission *PermissionConfig `json:"permission,omitempty"`
}

type SignatureVerification 

type SignatureVerification struct {
	Algorithm string
	Key       []byte
}

SignatureVerification 签名验证

func NewSignatureVerification 

func NewSignatureVerification(config *ModConfig) *SignatureVerification

NewSignatureVerification 创建签名验证实例

func (*SignatureVerification) Sign 

func (s *SignatureVerification) Sign(data []byte) ([]byte, error)

Sign 生成签名

func (*SignatureVerification) Verify 

func (s *SignatureVerification) Verify(data []byte, signature []byte) error

Verify 验证签名

type StdReply 

type StdReply struct {
	// contains filtered or unexported fields
}

func (StdReply) Code 

func (r StdReply) Code() int

func (StdReply) Detail 

func (r StdReply) Detail() string

func (StdReply) Error 

func (r StdReply) Error() string

func (StdReply) Msg 

func (r StdReply) Msg() string

type SymmetricEncryption 

type SymmetricEncryption struct {
	Algorithm string
	Key       []byte
}

SymmetricEncryption 对称加密

func NewSymmetricEncryption 

func NewSymmetricEncryption(config *ModConfig) (*SymmetricEncryption, error)

NewSymmetricEncryption 创建对称加密实例

func (*SymmetricEncryption) Decrypt 

func (s *SymmetricEncryption) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt 对称解密

func (*SymmetricEncryption) Encrypt 

func (s *SymmetricEncryption) Encrypt(plaintext []byte) ([]byte, error)

Encrypt 对称加密

type TokenResponse 

type TokenResponse struct {
	AccessToken           string `json:"access_token"`
	RefreshToken          string `json:"refresh_token"`
	AccessTokenExpiresIn  int64  `json:"access_token_expires_in"`
	RefreshTokenExpiresIn int64  `json:"refresh_token_expires_in"`
	TokenType             string `json:"token_type"`
}

TokenResponse represents the token response structure

Source Files

View all Source files

Directories

Path Synopsis
examples
basic-services command
encryption command
file-upload command
jwt-auth command
logging command
mock command
static-files command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.