14 KiB

Raw Blame History

BSM-SDK Core

BSM-SDK Core 是一个企业级后端开发工具包的核心模块，提供了微服务架构、配置管理、加密解密、缓存、数据库访问、中间件等基础功能。

私有仓库设置

go env -w GOPRIVATE=git.apinb.com/*
go env -w GONOPROXY=git.apinb.com/*
go env -w GOINSECURE=git.apinb.com/*
go env -w GONOSUMDB=git.apinb.com/*

核心功能模块

1. 服务管理 (service)

服务启动与注册

Service: 核心服务结构，支持 gRPC 服务启动和 etcd 注册
New(): 创建服务实例
Start(): 启动服务，支持 etcd 注册和 HTTP 网关
Stop(): 优雅停止服务
Use(): 执行初始化函数

服务发现

FoundGrpcMethods(): 自动发现 gRPC 方法
RegisterService(): 注册服务到 etcd
ServiceRegister: 服务注册器，支持租约管理

元数据解析

ParseMetaCtx(): 解析 gRPC 上下文中的元数据
ParseOptions: 解析选项，支持角色验证和私有IP检查

2. 配置管理 (conf)

配置加载

New(): 加载配置文件，支持环境变量替换
NotNil(): 验证必需配置项
PrintInfo(): 打印配置信息
CheckPort(): 检查端口配置

配置类型

MicroServiceConf: 微服务配置
GatewayConf: 网关配置
DBConf: 数据库配置

3. 加密与解密 (crypto)

AES 加密

AESGCMEncrypt/AESGCMDecrypt: GCM 模式加密解密
Encrypt/Decrypt: CBC 模式加密解密
AesEncryptECB/AesDecryptECB: ECB 模式加密解密
AesKeyCheck(): 密钥环境变量检测

RSA 加密

EncryptWithPublicKey(): 公钥加密
Decrypt(): 私钥解密

通用加密

AesEncryptCBC/AesDecryptCBC: 通用 CBC 加密解密
PKCS7Padding/PKCS7UnPadding: PKCS7 填充

4. 数据库支持 (database)

数据库连接

NewDatabase(): 创建数据库连接，支持 MySQL 和 PostgreSQL
NewMysql(): MySQL 连接
NewPostgres(): PostgreSQL 连接

数据库类型

SqlOptions: 数据库连接选项
Std_IICUDS: 标准数据库模型（ID、Identity、Created、Updated、Deleted、Status）
Std_ICUD: 标准数据库模型（ID、Created、Updated、Deleted）
Std_Passport: 护照模型
Std_Owner: 所有者模型

5. 缓存支持 (cache)

Redis 缓存

RedisClient: Redis 客户端封装
New(): 创建 Redis 连接
Hash(): 哈希分片计算

内存缓存

支持内存缓存操作

6. 消息队列 (queue)

NATS 消息队列

Nats: NATS 客户端封装
NewNats(): 创建 NATS 连接
Subscribe(): 订阅消息
Producer(): 发布消息

7. 中间件 (middleware)

JWT 认证

JwtAuth(): JWT 认证中间件
ParseAuth(): 解析认证信息

CORS 支持

Cors(): CORS 中间件

运行模式

Mode(): 设置 Gin 运行模式

8. 工具类 (utils)

网络工具 (net.go) ✨ 新增超时功能

完整的网络工具集，所有HTTP请求都支持超时控制。

IP地址工具：

IsPublicIP(ipString): 判断是否为公网IP
- 识别私有网段（10.x.x.x、172.16-31.x.x、192.168.x.x）
- 识别回环地址和链路本地地址
- 性能：62.55 ns/op，零内存分配
GetLocationIP(): 获取本机第一个有效IPv4地址
- 自动跳过回环和链路本地地址
- 返回 "127.0.0.1" 如果找不到
LocalIPv4s(): 获取本机所有IPv4地址列表
- 返回所有非回环IPv4地址
- 自动过滤链路本地地址
GetOutBoundIP(): 获取外网IP地址

HTTP请求工具（带超时保护）：

HttpGet(url, timeout...): HTTP GET请求
- 默认超时：30秒
- 支持自定义超时
- Context超时控制
- 示例：body, _ := HttpGet("https://api.com", 5*time.Second)
HttpPost(url, headers, data, timeout...): HTTP POST请求
- 默认超时：30秒
- 自动设置Content-Type和Request-Id
- 检查HTTP状态码
- 示例：body, _ := HttpPost(url, headers, data, 10*time.Second)
HttpPostJSON(url, headers, data): HTTP POST JSON请求
- 自动JSON序列化
- 继承HttpPost所有特性
- 示例：body, _ := HttpPostJSON(url, map[string]any{"key": "value"})
HttpRequest(request, timeout...): 执行自定义HTTP请求
- 支持任何HTTP方法
- 完全自定义请求

DownloadFile(url, savePath, progressCallback, timeout...): 文件下载

默认超时：5分钟
实时进度回调
文件权限：0644
缓冲区大小：32KB

示例：

progress := func(total, downloaded int64) {
    percent := float64(downloaded) / float64(total) * 100
    fmt.Printf("下载: %.2f%%\n", percent)
}
err := DownloadFile(url, "file.zip", progress, 10*time.Minute)

配置常量：

DefaultHTTPTimeout: 30秒（HTTP请求默认超时）
DefaultDownloadTimeout: 5分钟（下载默认超时）
DefaultBufferSize: 32KB（默认缓冲区）

二维码生成 (qrcode.go) 🎨 全新功能

完整的二维码生成工具，支持多种输出格式和自定义配置。

基础生成：

GenerateQRCode(content, filename, size...): 生成二维码文件
- 默认尺寸：256x256
- 支持自定义尺寸（21-8192像素）
- 中级纠错（15%容错）
- 示例：GenerateQRCode("https://example.com", "qr.png", 512)
GenerateQRCodeBytes(content, size...): 生成字节数组
- PNG格式
- 适合HTTP响应、数据库存储
- 性能：~1.5ms/次
- 示例：bytes, _ := GenerateQRCodeBytes("内容", 300)
GenerateQRCodeBase64(content, size...): 生成Base64编码
- 便于JSON传输
- 适合数据库文本字段
- 示例：base64Str, _ := GenerateQRCodeBase64("内容")
GenerateQRCodeDataURL(content, size...): 生成Data URL
- 可直接用于HTML 标签
- 包含完整图片数据
- 示例：dataURL, _ := GenerateQRCodeDataURL("内容")

高级功能：

GenerateQRCodeWithConfig(content, config): 自定义配置生成

自定义尺寸、颜色、纠错级别

示例：

config := &QRCodeConfig{
    Size: 512,
    ErrorLevel: QRCodeErrorLevelHigh,
    ForegroundColor: color.RGBA{255, 0, 0, 255}, // 红色
    BackgroundColor: color.White,
}
bytes, _ := GenerateQRCodeWithConfig("内容", config)

GenerateQRCodeWithLogo(content, logoPath, size...): 带Logo二维码
- Logo占据中心1/5区域
- 高级纠错（30%容错）
- 建议尺寸>=512
- 示例：bytes, _ := GenerateQRCodeWithLogo("内容", "logo.png", 512)

BatchGenerateQRCode(items, size...): 批量生成

一次生成多个二维码
返回失败列表

示例：

items := map[string]string{
    "产品A": "qr_a.png",
    "产品B": "qr_b.png",
}
failed, _ := BatchGenerateQRCode(items, 300)

纠错级别：

QRCodeErrorLevelLow: 低级纠错（~7%容错）
QRCodeErrorLevelMedium: 中级纠错（~15%容错，默认）
QRCodeErrorLevelQuartile: 较高级纠错（~25%容错）
QRCodeErrorLevelHigh: 高级纠错（~30%容错，适合Logo）

实用场景：

URL分享、名片（vCard）、WiFi连接
支付码、位置信息、文本分享
产品标签、会员卡、门票优惠券

性能指标：

生成速度：1.5-2.2 ms/次
内存占用：~984 KB/次
并发安全：所有函数都是并发安全的

数据类型转换

String2Int/String2Int64: 字符串转整数
String2Float64/String2Float32: 字符串转浮点数
Int2String/Int642String: 整数转字符串
Float64ToString/Float32ToString: 浮点数转字符串
AnyToString(): 任意类型转字符串

时间处理

Time2String(): 时间转字符串
String2Time(): 字符串转时间

身份标识

UUID(): 生成 UUID
ULID(): 生成 ULID

文件操作

PathExists(): 检查路径是否存在
CreateDir(): 创建目录
GetRunPath(): 获取运行路径
GetCurrentPath(): 获取当前路径

JSON 处理

JsonEscape(): JSON 转义

9. 错误处理 (errcode)

标准错误码

Header 错误: 101-104
标准错误: 110-121
JWT 错误: 131-139
模型错误: 151-157
gRPC 错误: 171-186

错误创建

NewError(): 创建标准错误
ErrFatal(): 创建致命错误
ErrNotFound(): 创建未找到错误

10. 响应处理 (infra)

统一响应

Reply: 统一响应结构
Success(): 成功响应
Error(): 错误响应，支持 gRPC 状态码转换

11. 日志打印 (printer)

彩色日志

Info(): 信息日志（白色）
Warn(): 警告日志（橙色）
Success(): 成功日志（绿色）
Error(): 错误日志（红色）
Json(): JSON 格式化输出

12. 环境管理 (env)

运行时环境

RuntimeEnv: 运行时环境配置
NewEnv(): 初始化环境
GetEnvDefault(): 获取环境变量默认值

13. 变量管理 (vars)

全局变量

ServiceKey: 服务键
HostName: 主机名
VERSION: 版本号
BUILD_TIME: 构建时间
GO_VERSION: Go 版本

14. 第三方集成 (third)

微信集成

支持微信相关功能

15. 许可证管理 (licence)

许可证验证

支持许可证文件验证

配置环境变量

export BSM_Workspace=def
export BSM_JwtSecretKey=your_secret_key
export BSM_RuntimeMode=dev
export BSM_Prefix=/usr/local/bsm

安全建议

使用强密钥进行加密
定期更新 JWT 密钥
配置适当的数据库连接池
使用 HTTPS 进行通信
定期检查许可证有效性

🚀 快速开始

网络工具示例

package main

import (
    "fmt"
    "time"
    "git.apinb.com/bsm-sdk/core/utils"
)

func main() {
    // 1. 获取本机IP
    localIP := utils.GetLocationIP()
    fmt.Printf("本机IP: %s\n", localIP)
    
    // 2. HTTP GET请求（带超时）
    body, err := utils.HttpGet("https://api.example.com/data", 5*time.Second)
    if err != nil {
        fmt.Printf("请求失败: %v\n", err)
        return
    }
    fmt.Printf("响应: %s\n", string(body))
    
    // 3. POST JSON数据
    headers := map[string]string{"Authorization": "Bearer token"}
    data := map[string]any{"name": "张三", "age": 25}
    body, err = utils.HttpPostJSON("https://api.example.com/users", headers, data)
    
    // 4. 下载文件（带进度）
    progress := func(total, downloaded int64) {
        if total > 0 {
            percent := float64(downloaded) / float64(total) * 100
            fmt.Printf("\r下载进度: %.2f%%", percent)
        }
    }
    err = utils.DownloadFile(
        "https://example.com/file.zip",
        "./download/file.zip",
        progress,
        10*time.Minute,
    )
}

二维码生成示例

package main

import (
    "fmt"
    "image/color"
    "git.apinb.com/bsm-sdk/core/utils"
)

func main() {
    // 1. 基础二维码
    err := utils.GenerateQRCode("https://example.com", "qrcode.png")
    
    // 2. 自定义尺寸
    err = utils.GenerateQRCode("内容", "qrcode_large.png", 512)
    
    // 3. 生成Base64（用于API响应）
    base64Str, _ := utils.GenerateQRCodeBase64("订单号：20231103001")
    fmt.Printf("Base64: %s\n", base64Str)
    
    // 4. 自定义颜色
    config := &utils.QRCodeConfig{
        Size: 512,
        ErrorLevel: utils.QRCodeErrorLevelHigh,
        ForegroundColor: color.RGBA{255, 0, 0, 255}, // 红色
        BackgroundColor: color.White,
    }
    bytes, _ := utils.GenerateQRCodeWithConfig("内容", config)
    utils.SaveQRCodeBytes(bytes, "red_qrcode.png")
    
    // 5. 批量生成
    items := map[string]string{
        "产品A": "qr_a.png",
        "产品B": "qr_b.png",
        "产品C": "qr_c.png",
    }
    failed, err := utils.BatchGenerateQRCode(items, 300)
    if err != nil {
        fmt.Printf("部分失败: %v\n", failed)
    }
    
    // 6. 名片二维码（vCard）
    vcard := `BEGIN:VCARD
VERSION:3.0
FN:张三
TEL:+86-138-0000-0000
EMAIL:zhangsan@example.com
ORG:某某公司
END:VCARD`
    utils.GenerateQRCode(vcard, "namecard.png", 400)
    
    // 7. WiFi连接二维码
    wifiInfo := "WIFI:T:WPA;S:MyWiFi;P:password123;;"
    utils.GenerateQRCode(wifiInfo, "wifi_qr.png", 300)
}

📝 使用建议

1. 配置管理

// 推荐使用环境变量进行配置
conf.New("your-service", &config)

2. 错误处理

// 使用统一的错误码
if err != nil {
    return errcode.ErrInternal
}

// 网络请求错误处理
body, err := utils.HttpGet(url, 5*time.Second)
if err != nil {
    // 判断是否为超时错误
    if errors.Is(err, context.DeadlineExceeded) {
        fmt.Println("请求超时")
    }
    return err
}

3. 缓存使用

// 使用统一的缓存键前缀
key := redisClient.BuildKey("user", userID)

4. 数据库连接

// 使用连接池优化
db, err := database.NewDatabase("mysql", dsn, options)

5. 二维码生成最佳实践

// 内容较长时增大尺寸
if len(content) > 100 {
    size = 512
} else {
    size = 256
}

// 添加Logo时使用高级纠错
config := &utils.QRCodeConfig{
    Size: 512,
    ErrorLevel: utils.QRCodeErrorLevelHigh, // 重要！
    ForegroundColor: color.Black,
    BackgroundColor: color.White,
}

许可证

本项目采用私有许可证，请确保已获得相应的使用授权。

贡献

欢迎提交 Issue 和 Pull Request 来改进本项目。

联系方式

如有问题，请联系开发团队。

14 KiB Raw Blame History Unescape Escape