README
¶
kratos-core
kratos-core 是 Kratos 服务的基础运行时。它负责把宿主项目提供的模块、配置和构建期资源装配成统一的 HTTP、gRPC、MCP、SSE、队列和任务服务。
Core 的跨项目入口只有根包提供的 ProviderSet 和 NewApplication；internal 目录中的数据、业务和运行时实现不作为外部模块 API。
快速接入
宿主项目在自己的 Wire 组合根中加入 core.ProviderSet：
//go:build wireinject
package main
import (
"github.com/go-kratos/kratos/v3"
"github.com/google/wire"
core "github.com/liujitcn/kratos-core"
"github.com/liujitcn/kratos-core/pkg/module"
"github.com/liujitcn/kratos-kit/bootstrap"
)
func initApp(
ctx *bootstrap.Context,
assets core.Assets,
modules module.Modules,
) (*kratos.App, func(), error) {
panic(wire.Build(core.ProviderSet))
}
Wire 生成的 initApp 最终调用：
app, cleanup, err := core.NewApplication(ctx, assets, modules)
if err != nil {
return err
}
defer cleanup()
return app.Run()
ctx 使用 kratos-kit/bootstrap.Context。Core 按其中的 server 配置创建服务；未配置的传输协议不会创建对应服务。
宿主资源
Core 不内嵌宿主项目的 OpenAPI、项目文档和数据库迁移文件。宿主项目负责生成或嵌入资源，再通过 Assets 传入：
| 字段 | 用途 |
|---|---|
OpenAPIData |
Core 基础服务的 OpenAPI YAML/JSON；用于 API 权限和文档路由。 |
DocsData |
项目文档生成器输出的 JSON；宿主项目文档由 Core 注册并注入模块。 |
Migrations |
Core 基础服务的版本化数据库迁移；资源由宿主项目提供。 |
三项资源都可以为空。模块自己的 OpenAPI、项目文档和迁移通过 pkg/module 的贡献接口提供。
当 Core 和模块都未提供 OpenAPI 时，启动不会覆盖数据库中已有的接口权限快照。
示例配置：
server:
http:
addr: :7001
grpc:
addr: :6001
mcp:
transport: TRANSPORT_IN_PROCESS
path: /mcp
sse:
transport: TRANSPORT_IN_PROCESS
path: /events
MCP 和 SSE 分别按 server.mcp、server.sse 配置创建独立服务或进程内处理器；进程内模式使用各自的 path 挂载。业务模块应在 RegisterHTTP 中注册受统一认证中间件保护的订阅路径；MCP 工具仍通过 RegisterMCP 注册。
模块契约
模块实现 module.Module，必须提供三个协议注册方法。不使用某个协议时保留空实现：
type demoModule struct{}
func (demoModule) RegisterGRPC(grpc.ServiceRegistrar) {}
func (demoModule) RegisterHTTP(*kratosHTTP.Server) {}
func (demoModule) RegisterMCP(*mcpserver.Server) {}
MCP 过滤器、处理器等模块自有配置应在 RegisterMCP 中完成。需要订阅或发布 SSE 的业务在 Runtime 初始化时直接使用 Runtime.SSEServer、Runtime.SSERegistry 和 Runtime.SSEPublisher，无需实现 Core 的额外服务注入接口。
模块可按需实现以下贡献接口：
ModelContributor：提供模块 GORM 模型。MigrationContributor：提供模块数据库迁移。OpenAPIContributor、ProjectDocumentContributor：提供 API 和项目文档。I18nContributor、StaticContributor：提供语言资源和静态文件挂载。TaskContributor、QueueConsumerContributor、SSEContributor：提供任务、队列消费者和 SSE 流。AIFixedFlowContributor：提供 AI 固定流程和快捷入口。HealthContributor、ScriptContributor、StartupContributor：提供健康检查、启动脚本和生命周期钩子。HTTPMiddlewareContributor、GRPCMiddlewareContributor、ServerContributor：追加中间件和后台服务。
业务 Case 可以嵌入 pkg/biz.BaseCase，获取 Bootstrap 上下文、Core 统一缓存、认证信息和队列能力。模块只需要依赖根包、pkg/module、pkg/biz 以及自己的 API 生成包。
AI 能力
Core 提供三组可复用的 AI 包，统一使用 kratos-kit 的 configv1.AI_Model 配置：
| 包 | 用途 |
|---|---|
github.com/liujitcn/kratos-core/pkg/agent/... |
提供 Admin Agent 消息、工具、Callback、Middleware、结构化任务和固定流程适配 |
这些包只负责客户端和编排封装，不会在 Core 启动时自动连接模型服务；业务模块按需创建并管理模型实例。
数据与迁移边界
Core 的 internal/data 使用原生 GORM 查询和事务封装，internal/data/models 只保留 Core 运行所需的最小模型字段和仓储。Core 不依赖 GORM Gen 的 query 代码。启用 data.database.enable_migrate 时，Core 和模块注册的模型会交给 GORM 自动创建或补齐表结构；关闭该选项时，表结构由迁移资源负责。
版本化迁移资源始终由宿主传入并执行，模块模型通过 ModelContributor 参与数据库客户端模型范围和自动迁移，模块的复杂结构变更仍应由模块自己的迁移提供。启用版本化迁移时，默认客户端还需要通过模型迁移创建 base_migration 记录表。
目录职责
api/
proto/ Core 公共 protobuf 定义
gen/go/ protobuf 生成的 Go 代码
pkg/
module/ 外部模块接口和资源贡献契约
biz/ 模块共享的 BaseCase 和 ProviderSet
const/ Core 公共常量
errorsx/ 统一错误构造
i18n/, locale/ 国际化和语言环境能力
openapi/ OpenAPI 文档注册与 HTTP 暴露
sse/ SSE 流注册和 JSON 发布
queue/ 面向业务调用的队列发布封装
task/ 任务注册与调度
internal/
biz/ Core 内置 API、租户和 Casbin 业务
data/ Core 模型、原生 GORM 查询和仓储
docs/ Core 内置项目文档
migration/ 宿主迁移资源的 Core 适配
health/, startup/ 健康检查和启动钩子管理
job/ Cron 服务
queue/ 队列生命周期适配
server/ HTTP、gRPC、MCP、SSE 服务装配
static/, i18n/ 静态资源和 Core 内置语言包
bootstrap.go 应用装配和统一生命周期
assets.go 宿主资源输入
provider.go 对外 ProviderSet 和 NewApplication
wire.go Core 内部 Wire 声明
wire_gen.go Wire 生成文件
启动流程
应用从宿主项目的 Wire 组合根开始，按以下顺序完成初始化：
- 入口与资源收集：宿主调用
core.ProviderSet，并把bootstrap.Context、Assets和模块集合传给NewApplication。Core 收集宿主资源以及模块贡献的模型、迁移、文档、语言包、静态文件和后台任务。 - 运行时依赖构建：Wire 创建数据库、缓存、认证、队列、任务、SSE 和各协议服务所需的运行时依赖。未配置的传输协议不会被创建。
- 数据库与权限同步：Core 执行宿主提供的迁移，初始化内置数据访问层，并同步基础 API、菜单和 Casbin 权限；初始化失败时立即返回错误。
- 服务装配：Core 注册模块的 HTTP、gRPC、MCP、SSE、队列和任务贡献，随后根据
server配置装配实际服务。每个服务都复用统一的中间件和国际化能力。 - 后台服务、启动与退出：启动钩子和后台消费者准备完成后运行 Kratos 应用。收到退出信号或启动失败时，Core 按依赖的逆序停止服务、取消任务并释放资源。
任一步骤返回错误都会停止后续初始化，并执行已经创建资源的清理流程。对应的核心实现位置如下：
| 阶段 | 主要实现 |
|---|---|
| 入口和资源收集 | bootstrap.go:newApplication、pkg/module/resources.go |
| Wire 运行时 | wire_gen.go、runtime_provider.go |
| 数据库和权限同步 | runtime_provider.go:newRuntime、internal/migration、internal/biz |
| 服务装配 | internal/server、internal/queue、pkg/sse、pkg/task |
| 启动和退出 | internal/startup、bootstrap.go 的 cleanup 流程 |
开发命令
# 生成 Core protobuf 代码
make api
# 格式化、测试和静态检查
make fmt
make test
make vet
make lint
# 重新生成 Wire 文件
go generate .
项目要求 Go 1.26.5。修改 Wire provider 或 protobuf 后，应重新生成对应产物并执行 make test 和 make vet。
Documentation
¶
Index ¶
- Variables
- func NewApplication(ctx *bootstrap.Context, assets Assets, modules module.Modules) (*kratos.App, func(), error)
- func NewApplicationWithOptions(ctx *bootstrap.Context, assets Assets, modules module.Modules, ...) (*kratos.App, func(), error)
- type ApplicationOption
- func WithGRPCMiddlewares(middlewares ...kratosMiddleware.Middleware) ApplicationOption
- func WithHTTPMiddlewares(middlewares ...kratosMiddleware.Middleware) ApplicationOption
- func WithHealthChecks(checks ...module.HealthCheck) ApplicationOption
- func WithQueue(queue kitQueue.Queue) ApplicationOption
- func WithQueueConsumers(consumers ...module.QueueConsumer) ApplicationOption
- func WithSSERegistry(registry *coreSSE.Registry) ApplicationOption
- func WithSSEServer(server *sseServer.Server) ApplicationOption
- func WithSSEServerListener(listener net.Listener) ApplicationOption
- func WithSSEStreams(streams ...module.SSEStream) ApplicationOption
- func WithScripts(scripts ...module.Script) ApplicationOption
- func WithServers(servers ...kratosTransport.Server) ApplicationOption
- func WithStartupHooks(hooks ...module.StartupHook) ApplicationOption
- func WithStaticMounts(mounts ...module.StaticMount) ApplicationOption
- func WithTasks(tasks ...module.Task) ApplicationOption
- type Assets
- type Runtime
- type RuntimeAware
Constants ¶
This section is empty.
Variables ¶
var ProviderSet = wire.NewSet(NewApplication)
ProviderSet 是 Core 对外唯一的 Wire 依赖注入入口。外部组合根只需要把本集合加入自己的 wire.Build；Core 内部的运行时对象图会由 NewApplication 统一创建，内部包不会泄漏到宿主项目的生成代码中。
Functions ¶
Types ¶
type ApplicationOption ¶
type ApplicationOption = option
ApplicationOption 表示宿主可传入的 Core 应用装配选项。
func WithGRPCMiddlewares ¶
func WithGRPCMiddlewares(middlewares ...kratosMiddleware.Middleware) ApplicationOption
WithGRPCMiddlewares 追加 gRPC 服务端拦截器。
func WithHTTPMiddlewares ¶
func WithHTTPMiddlewares(middlewares ...kratosMiddleware.Middleware) ApplicationOption
WithHTTPMiddlewares 追加 HTTP 服务端拦截器。
func WithHealthChecks ¶
func WithHealthChecks(checks ...module.HealthCheck) ApplicationOption
WithHealthChecks 追加组合根提供的就绪检查。
func WithQueue ¶
func WithQueue(queue kitQueue.Queue) ApplicationOption
WithQueue 注入队列适配器；未注入时由 Core 根据配置创建。
func WithQueueConsumers ¶
func WithQueueConsumers(consumers ...module.QueueConsumer) ApplicationOption
WithQueueConsumers 追加组合根提供的队列消费者。
func WithSSERegistry ¶
func WithSSERegistry(registry *coreSSE.Registry) ApplicationOption
WithSSERegistry 使用调用方创建的 SSE 注册表。
func WithSSEServer ¶
func WithSSEServer(server *sseServer.Server) ApplicationOption
WithSSEServer 注入由宿主创建的 SSE 服务。
func WithSSEServerListener ¶
func WithSSEServerListener(listener net.Listener) ApplicationOption
WithSSEServerListener 注入由 Core 管理生命周期的独立 SSE 监听器。
func WithSSEStreams ¶
func WithSSEStreams(streams ...module.SSEStream) ApplicationOption
WithSSEStreams 追加组合根提供的 SSE 流。
func WithScripts ¶
func WithScripts(scripts ...module.Script) ApplicationOption
WithScripts 追加组合根提供的启动脚本。
func WithServers ¶
func WithServers(servers ...kratosTransport.Server) ApplicationOption
WithServers 追加需要跟随 Core 生命周期运行的后台服务。
func WithStartupHooks ¶
func WithStartupHooks(hooks ...module.StartupHook) ApplicationOption
WithStartupHooks 追加组合根提供的启动钩子。
func WithStaticMounts ¶
func WithStaticMounts(mounts ...module.StaticMount) ApplicationOption
WithStaticMounts 追加组合根提供的静态资源挂载。
type Assets ¶
type Assets struct {
// OpenAPIData 是可选的 Core 基础服务 OpenAPI YAML 或 JSON 内容。
OpenAPIData []byte
// DocsData 是可选的项目文档生成器输出 JSON 内容。
DocsData []byte
// Migrations 是可选的 Core 基础服务版本化迁移资源。
Migrations []gormmigration.Migration
}
Assets 是宿主项目传入 Core 的构建期资源。
type Runtime ¶
type Runtime struct {
// Context 是 Core 使用的宿主启动上下文。
Context *bootstrap.Context
// Cache 是 Core 与模块共享的缓存客户端。
Cache cache.Cache
// Queue 是 Core 与模块共享的队列客户端。
Queue queue.Queue
// Database 是 Core 与模块共享的数据库客户端。
Database *databaseGorm.Client
// Pprof 是 Core 使用的性能分析客户端。
Pprof pprof.Pprof
// Authenticator 是 Core 与模块共享的认证器。
Authenticator authnEngine.Authenticator
// Authorizer 是 Core 与模块共享的鉴权引擎。
Authorizer authzEngine.Engine
// UserToken 是 Core 与模块共享的用户令牌存储。
UserToken *authData.UserToken
// JWTConfig 是 Core 使用的 JWT 配置。
JWTConfig *bootstrapConfigv1.Authentication_Jwt
// TaskRegistry 是 Core 与模块共享的任务注册表。
TaskRegistry *coreTask.Registry
// JobScheduler 是 Core 与模块共享的持久化定时任务调度器。
JobScheduler coreTask.JobScheduler
// OpenAPIRegistry 是 Core 与模块共享的 OpenAPI 注册表。
OpenAPIRegistry *coreOpenAPI.Registry
// SSEServer 是 Core 与模块共享的 SSE 服务。
SSEServer *sseServer.Server
// SSERegistry 是模块共享的 SSE 流注册表。
SSERegistry *coreSSE.Registry
// SSEPublisher 是模块共享的 SSE 消息发布器。
SSEPublisher *coreSSE.Publisher
}
Runtime 是 Core 初始化完成后向外部业务模块公开的共享运行时。
type RuntimeAware ¶
type RuntimeAware interface {
// Initialize 使用 Core 运行时完成模块装配，并返回模块资源清理函数。
Initialize(*Runtime) (func(), error)
}
RuntimeAware 表示需要在 Core 运行时就绪后完成业务装配的外部模块。
Source Files
Directories