jxt-core

jxt-core - 企业级微服务基础框架

项目简介

jxt-core 是一个基于 Go 语言的企业级微服务基础框架，提供了构建现代化分布式应用所需的核心组件和工具。框架采用模块化设计，支持多种部署模式，适用于大型企业级应用开发。

核心特性

🚀 基础设施组件

• 日志组件 - 基于 zap 的高性能结构化日志，支持多种输出格式和日志分级
• 配置管理 - 基于 viper 的多格式配置支持（YAML、JSON、TOML等）
• 缓存系统 - 支持 Memory、Redis 多种缓存后端
• 消息队列 - 支持 Memory、Redis、NSQ 多种队列实现
• 分布式锁 - 基于 Redis 的分布式锁实现
• EventBus 事件总线 - 支持 Kafka、NATS JetStream、Memory 三种实现，统一 API ⭐ 核心组件
• Outbox 模式 - 保证业务操作与事件发布的原子性和最终一致性；同步/异步发布器标记分流 + 批量标记（v2.0.0）、异步 ACK 攒批（v1.1.59）⭐
• 多租户 Provider - 基于 ETCD 的多租户配置管理，支持实时监听、租户识别配置缓存 ⭐ 核心组件

🔧 服务治理

• 服务发现 - 基于 ETCD 的服务注册与发现
• gRPC 支持 - 完整的 gRPC 服务端和客户端实现
• HTTP 服务 - 基于 Gin 的 RESTful API 支持
• 负载均衡 - 支持多种负载均衡策略
• 监控指标 - 集成 Prometheus 监控指标收集

🔐 安全认证

• JWT 认证 - 完整的 JWT token 生成和验证
• 权限控制 - 基于 Casbin 的 RBAC 权限管理
• 验证码 - 图形验证码生成和验证
• 加密工具 - 常用的加密解密工具集

📡 通信协议

• WebSocket - 实时双向通信支持
• gRPC - 高性能 RPC 通信
• HTTP/HTTPS - 标准 Web API 支持

💾 数据存储

• 多数据库支持 - MySQL、PostgreSQL、SQLite、SQL Server
• ORM 集成 - 基于 GORM 的数据库操作
• 读写分离 - 支持主从数据库配置
• 事务管理 - 完整的数据库事务支持
• 服务级数据库配置 - 支持为每个租户的每个微服务配置独立数据库 ⭐ 新增

⏰ 任务调度

• 定时任务 - 基于 cron 的任务调度
• 异步任务 - 基于队列的异步任务处理

🛠 开发工具

• 代码生成 - 自动生成常用代码模板
• 工具函数 - 丰富的工具函数库
• 中间件 - 常用的 HTTP 中间件
• 响应封装 - 统一的 API 响应格式

快速开始

环境要求

• Go 1.26+
• Redis 6.0+ (可选)
• MySQL 8.0+ / PostgreSQL 12+ (可选)
• ETCD 3.5+ (用于服务发现和多租户配置，可选)
• Ginkgo/Gomega (测试框架，可选)

安装

go get github.com/ChenBigdata421/jxt-core

基本使用

package main

import (
	"github.com/ChenBigdata421/jxt-core/sdk"
	"github.com/ChenBigdata421/jxt-core/sdk/config"
)

func main() {
	// 1. 加载配置文件（viper 解析 settings.yml 到 sdk/config.AppConfig）
	config.Setup("config/settings.yml")

	// 2. sdk.Runtime 是框架预初始化的单例（实现 runtime.Runtime 接口），
	//    通过它装配 / 获取各组件，例如：
	//      sdk.Runtime.SetEngine(engine)   // HTTP 路由引擎
	//      sdk.Runtime.SetEventBus(bus)    // 事件总线
	//      sdk.Runtime.SetTenantDB(id, db) // 租户数据库
	_ = sdk.Runtime
}

配置示例

# 应用配置
application:
  name: "my-service"
  mode: "dev"
  version: "1.0.0"

# HTTP 服务配置
http:
  host: "0.0.0.0"
  port: 8080

# 数据库配置
database:
  driver: "mysql"
  source: "user:pass@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"

# 缓存配置
cache:
  redis:
    addr: "localhost:6379"
    password: ""
    db: 0

# 日志配置
logger:
  level: "info"
  path: "./logs"

### 多租户配置（Tenants）

框架内置统一的多租户配置，结构定义见 `sdk/config/tenant.go`。核心能力包括：

- `resolver`：支持 HTTP（host/header/query/path 四种模式）与 FTP（username/password）双通道识别；
- `storage`：配置多租户租户目录名（默认 `tenants`，最终路径为 `./uploads/<directory>/<tenant_id>`）；
- `default`：提供默认租户的数据库、域名、FTP 与存储限额等完整初始化信息，首次创建租户时可直接写入数据库。

示例配置：

```yaml
tenants:
  resolver:
    http:
      type: host               # host/header/query/path
      hostMode: numeric        # type=host 时的模式：numeric（默认）/domain/code
      headerName: X-Tenant-ID   # type=header 时的 Header 名
      queryParam: tenant        # type=query 时的 Query Key
      pathIndex: 0              # type=path 时的路径索引
    ftp:
      type: username            # username/password

  storage:
    directory: tenants

  default:
    database:
      driver: postgres
      host: postgres-tenant
      port: 5432
      database: tenant-servicedb
      username: tenant
      password: password123
      sslmode: disable
      max_open_conns: 50
      max_idle_conns: 10
      conn_max_idle_time: 300
      conn_max_life_time: 3600
      connect_timeout: 10
      read_timeout: 30
      write_timeout: 30

    domain:
      primary: app.example.com
      aliases:
        - www.example.com
      internal: app.internal

    ftp:
      username: default_ftp
      initial_password: Default@123456

    storage:
      upload_quota_gb: 1000
      max_file_size_mb: 2048
      max_concurrent_uploads: 20

更详细的字段含义与环境变量映射，请参考 docs/tenant.yml。

服务级数据库配置 ⭐

框架支持为每个租户的每个微服务配置独立的数据库连接，实现更细粒度的数据隔离和性能优化。

配置示例

tenants:
  default:
    service_databases:
      evidence-command:
        driver: mysql
        host: mysql-command
        port: 3306
        database: tenant_command

      evidence-query:
        driver: postgres
        host: postgres-query
        port: 5432
        database: tenant_query

      file-storage:
        driver: postgres
        host: postgres-storage
        port: 5432
        database: tenant_storage

      security-management:
        driver: postgres
        host: postgres-security
        port: 5432
        database: securitydb

使用方法

// 设置服务数据库连接
app.SetTenantServiceDB(tenantID, "evidence-command", db)

// 获取服务数据库连接
db := app.GetTenantServiceDB(tenantID, "evidence-command")

// 遍历所有服务数据库连接
app.GetTenantServiceDBs(func(tenantID int, serviceCode string, db *gorm.DB) bool {
    fmt.Printf("租户 %d 的 %s 服务数据库\n", tenantID, serviceCode)
    return true
})

支持的服务代码

• evidence-command - 证据管理写服务（CQRS Command 端）
• evidence-query - 证据管理读服务（CQRS Query 端）
• file-storage - 文件存储服务
• security-management - 安全管理服务

向后兼容

旧的 API 仍然可用，并自动映射到服务级配置：

// 这些方法仍然可用，内部映射到服务级配置
db := app.GetTenantDB(tenantID)              // 映射到 security-management

详细文档参见: 服务级数据库配置指南

EventBus 事件总线 ⭐

核心特性

• 统一 API：Kafka、NATS JetStream、Memory 三种实现共享同一套接口
• Hollywood Actor Pool：基于 Actor 模型的消息处理，256 个 Actor 并发处理
• 双模式支持：
  • Subscribe：高性能无序并发处理（Round-Robin 路由）
  • SubscribeEnvelope：聚合ID 顺序保证（一致性哈希路由）
• 多语义保证：
  • At-Most-Once（Memory、普通消息）
  • At-Least-Once（Kafka/NATS Envelope）
• 高性能编码：
  • 默认：JSON（jsoniter，比标准库快 2-3 倍）
  • 可选：Protobuf、Avro、CloudEvents
• Outbox 集成：与 Outbox 模式无缝集成，保证事件发布可靠性
• 故障隔离：Supervisor 自动重启机制，单个聚合故障不影响其他聚合
• 性能监控：集成 Prometheus 指标，实时监控吞吐量、延迟、错误率

性能指标

• 吞吐量：1900+ msg/s（单实例）
• 延迟：0.5ms（P99）
• 并发处理：256 Actor 并发
• 内存占用：3.4 MB（1000 条消息）
• 监控开销：Kafka ~3.9%，NATS ~24.5%

编码方式选型

详见 EventBus 文档

项目结构

jxt-core/
├── sdk/                       # 核心 SDK
│   ├── runtime/              # 应用运行时（Application 单例：租户/服务级 DB、Casbin、Cron、EventBus 装配）
│   ├── config/               # 配置管理（settings.yml 解析、多租户配置、Redis 多客户端）
│   ├── api/                  # 通用 API 请求/响应绑定类型
│   ├── antd_api/             # Ant Design Pro 风格 API 绑定类型
│   ├── restapi/              # REST API 类型定义
│   ├── middleware/           # HTTP 中间件
│   ├── service/              # 服务层
│   └── pkg/                  # 核心组件包
│       ├── eventbus/         # 事件总线（Kafka/NATS/Memory）⭐
│       ├── outbox/           # Outbox 模式实现 ⭐
│       ├── domain/           # 领域事件模型 ⭐
│       ├── tenant/           # 多租户组件（ETCD Provider + 配置缓存）⭐
│       │   ├── provider/     # ETCD 配置 Provider
│       │   ├── cache/        # 本地文件缓存实现
│       │   ├── database/     # 数据库配置缓存
│       │   ├── ftp/          # FTP 配置缓存
│       │   ├── storage/      # 存储配置缓存
│       │   ├── wvp/          # WVP 配置缓存
│       │   └── middleware/   # 租户 ID 提取中间件
│       ├── logger/           # 日志组件（zap）
│       ├── json/             # 统一 JSON 编码（jsoniter）
│       ├── contextpool/      # Context 对象池
│       ├── jwtauth/          # JWT 认证
│       ├── casbin/           # 权限控制（多租户 + PSUBSCRIBE 策略同步）
│       ├── captcha/          # 验证码
│       ├── crypto/           # 加密工具（AES-256-GCM）
│       ├── ws/               # WebSocket
│       ├── cronjob/          # 定时任务
│       ├── migration/        # 数据库迁移框架
│       ├── response/         # 统一响应封装
│       ├── table/            # 表结构分析（代码生成）
│       └── utils/            # 工具函数
├── storage/                   # 存储适配层
│   ├── cache/                # 缓存实现（Memory/Redis）
│   ├── queue/                # 队列实现（Memory/Redis/NSQ）
│   └── locker/               # 分布式锁（Redis）
├── errors/                    # 统一错误码
├── debug/                     # 日志文件 writer
├── tests/                     # 测试套件
│   ├── eventbus/             # EventBus 测试
│   │   ├── performance_regression_tests/  # 性能回归测试
│   │   ├── reliability_regression_tests/  # 可靠性测试
│   │   └── function_tests/                # 功能测试
│   ├── outbox/               # Outbox 测试
│   ├── config/               # 配置测试
│   └── domain/               # 领域事件测试
├── examples/                  # 使用示例
├── tools/                     # 开发工具（database/etcd/poster/search/transfer/language/utils）
└── docs/                      # 文档

文档

核心文档

• 文档中心 - 完整的文档索引
• EventBus 文档 - 事件总线使用指南
• Outbox 模式快速开始 ⭐ - 5 分钟快速上手
• Outbox 模式完整设计 - 完整的架构设计和使用指南

贡献

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

许可证

本项目采用 Apache 2.0 许可证。

架构优化

Hollywood Actor Pool 架构

• 统一消息处理：Kafka、NATS、Memory 三种实现都使用同一个 Actor Pool
• 智能路由：
  • 有聚合ID：一致性哈希路由到固定 Actor，保证顺序
  • 无聚合ID：Round-Robin 轮询路由，最大化并发
• 故障隔离：每个聚合独立 Actor，单个故障不影响全局
• 自动恢复：Supervisor 机制自动重启失败的 Actor
• 背压控制：Inbox 队列（1000 容量）提供背压机制

NATS ACK Worker Pool

• 异步 ACK 处理：固定大小的 worker 池（默认 2×CPU 核心数）
• CSP 实现：基于 Go 原生 channel + goroutine
• 超时保护：30 秒 ACK 超时，避免永久阻塞
• 多租户支持：支持租户专属 ACK 通道

多租户 Provider 架构

• ETCD 配置中心：基于 ETCD 存储租户配置，支持实时监听变更
• 三类配置支持：Database、FTP、Storage 配置独立管理
• 原子更新：使用 atomic.Value 保证配置读取的线程安全
• Watch 机制：自动监听 ETCD 变更，实时同步配置
• Gin 中间件：ExtractTenantID 中间件自动提取租户 ID

租户识别方式

框架支持四种 HTTP 租户识别方式：

域名识别（host 类型）支持三种互斥模式：

通过配置 hostMode（YAML）或 httpHostMode（ETCD）设置，三种模式互斥，不可同时使用：

配置方式：

# YAML 配置方式
tenants:
  resolver:
    http:
      type: host
      hostMode: numeric  # numeric/domain/code，默认 numeric

// ========== Host 类型租户识别 - 三种互斥模式 ==========

// 模式1：numeric（默认）- 仅数字子域名（无 Provider）
// - 123.example.com ✅ → 租户 ID 123
// - 456.app.example.com ✅ → 租户 ID 456
// - acmecorp.example.com ❌ → 非数字，识别失败
router.Use(ExtractTenantID(WithResolverType("host")))

// 推荐方式：通过 Provider 自动从 ETCD 读取全部租户识别配置
// 支持四种 httpType：host/header/query/path（由 ETCD httpType 配置决定）
// - host 模式支持三种子模式：numeric/domain/code（由 ETCD httpHostMode 配置决定）
router.Use(ExtractTenantID(
    WithProviderConfig(provider),
))

// ========== 其他租户识别方式（无 Provider） ==========

// Header 识别
router.Use(ExtractTenantID(
    WithResolverType("header"),
    WithHeaderName("X-Tenant-ID"),
))

// Query 参数识别
router.Use(ExtractTenantID(
    WithResolverType("query"),
    WithQueryParam("tenant"),
))

// URL 路径识别
// 例如: /123/users -> 提取第0段 "123" 作为租户 ID
router.Use(ExtractTenantID(
    WithResolverType("path"),
    WithPathIndex(0),
))

重要说明：

1. 互斥性：三种模式只能选择一种，不会回退到其他模式
2. 默认值：hostMode 默认为 numeric，保持向后兼容
3. 大小写：code 模式下，子域名会转为小写后匹配（DNS 大小写不敏感）
4. 配置来源：hostMode 优先从 Provider 的 GetResolverConfig() 获取，支持 ETCD 动态配置

使用示例

// 创建 ETCD 客户端
client, _ := clientv3.New(clientv3.Config{
    Endpoints: []string{"localhost:2379"},
})

// 创建 Provider
p := provider.NewProvider(client,
    provider.WithNamespace("jxt/"),
    provider.WithConfigTypes(
        provider.ConfigTypeDatabase,
        provider.ConfigTypeFtp,
        provider.ConfigTypeStorage,
    ),
)

// 加载所有租户配置
p.LoadAll(ctx)

// 启动 Watch 监听变更
p.StartWatch(ctx)

// 获取租户某服务的数据库配置（serviceCode 如 "security-management"）
dbConfig, ok := p.GetServiceDatabaseConfig(tenantID, "security-management")

性能测试覆盖

• ✅ 高吞吐量场景（1900+ msg/s）
• ✅ 低延迟处理（0.5ms）
• ✅ 消息顺序保证
• ✅ 故障隔离与恢复
• ✅ 协程泄漏检测
• ✅ 内存使用监控

版本历史

• v1.1.58 - Outbox v2.0.0：SyncSemanticsPublisher 同步/异步标记分流；FindPublishedByIdempotencyKeys 批量幂等检查；BatchUpdate 更名为 MarkBatchAsPublished（单条 UPDATE 状态迁移，幂等 WHERE status='pending'）；filterPublishedEvents 批量化（破坏性接口变更）
• v1.1.57 - EventBus 新增 TopicPartitionInfo 可选接口（分区查询）；修复 create_or_update 未扩已有 topic 分区
• v1.1.56 - EventBus Kafka 消费分区流水线优化（partitionPipeline，feature flag 默认关闭）：advanceFrontier 连续前缀提交 + 异步 DLQ + Strategy A poison stall + 同聚合顺序保证；P-1 正确性门全绿，P-2 灰度前置待定
• v1.1.55 - README 刷新对齐代码、移除 go-admin 残留引用、Go toolchain 升级到 1.26.0、示例 main 加 //go:build ignore
• v1.1.53 - Casbin 精简（破坏性变更）：移除 SetupForTenant/Setup、去除 gorm-adapter 依赖（SetupForTenant 下沉至 security-management 自建本地 GormAdapter）；导出 watcher 初始化与 model 文本；新增 Linux-CI Sentinel 故障转移集成测试
• v1.1.52 - Redis Sentinel 支持：新增 Sentinel 字段与 newClient、合并 QueueRedis/QueueNSQ；按 DB 幂等客户端（5 个 Ensure*）；订阅者 ping 收敛到写锁、移除无用的 NSQ squash；同步 casbin/redis README
• v1.1.51 - Redis 基础设施重构：升级 go-redis 到稳定 v9.x（移除 redisqueue）、落地三客户端架构（共享/队列消费者/订阅者）；新增后台健康检查 IsRedisHealthy()、context-aware AdapterCache 接口、优雅 Close()；Casbin 策略同步改为单连接 PSUBSCRIBE 多路复用 + 8 分片有序派发；修复缓存/队列多处数据竞争
• v1.1.50 - StorageConfig 新增 PublicUrl 字段，支持外部代理访问地址
• v1.1.49 - 新增 WVP（视频平台）配置缓存：Provider 支持 ConfigTypeWvp / GetWvpConfig / WVP watch 事件；新增 tenant/wvp 缓存包与 TenantWvpConfig 模型；配套单元测试与设计文档
• v1.1.48 - 多租户默认配置（DefaultTenantConfig）新增 TenantWvpDetailConfig，支持 settings.yml 初始化 WVP 配置
• v1.1.47 - Outbox 新增 InProcessEventPublisher，支持进程内事件分发
• v1.1.46 - Provider 新增 GetAllTenantIDs 方法；jwtauth 将 Dept 字段重命名为 Org（语义清晰）
• v1.1.45 - 新增租户识别配置缓存，支持基于配置缓存进行租户识别
• v1.1.41 - 新增域名查找（DomainLookuper）支持租户 ID 解析
• v1.1.40 - 增强租户 ID 解析能力
• v1.1.39 - 新增域名查找支持
• v1.1.38 - 新增统一迁移框架支持多租户
• v1.1.36 - 增加 *.prof 到 gitignore
• v1.1.35 - Casbin 缓存优化，通过 gRPC 获取策略
• v1.1.31 - 支持每个租户多个 FTP 配置
• v1.1.30 - 支持租户服务数据库配置
• v1.1.29 - 新增多租户组件
• v1.1.28 - 重构 tenants 结构，增加缺省租户
• v1.1.27 - ETCD 增加租户配置
• v1.1.26 - 增加 FTP 配置、存储站点配置
• v1.1.25 - Worker pool 迁移到 Hollywood Actor Pool
• v1.1.20 - 新增 Outbox 组件
• v1.1.19 - 新增 EventBus 组件
• v1.1.18 - 完善 GRPC 配置
• v1.1.16 - 多租户支持，重构 casbin 和 crontab
• v1.1.11 - 增加多租户配置
• v1.1.0 - 移除本地 SDK 模块 replace 指令
• v1.0.0 - 初始版本，提供基础框架功能