krathub

module

v0.1.0-alpha.1 Latest Latest Go to latest Published: Jan 17, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/horonlee/krathub

Links

Open Source Insights

README ¶

Krathub

English | 简体中文

Krathub 是一个基于 Go Kratos 框架的微服务项目示例。它展示了现代化微服务架构的最佳实践，采用 Buf 进行 Protobuf 管理，支持多服务架构，可作为学习参考或作为新项目的起点。

✨ 核心特性

现代化微服务架构: 基于 Kratos v2 构建，支持多服务独立开发和部署
Buf 工具链: 使用 Buf 进行 Protobuf 管理，提供更好的依赖管理和代码生成体验
双协议支持: 同时提供 gRPC 和 HTTP 接口，满足不同场景需求
统一 OpenAPI 生成: 自动为每个服务生成独立的 OpenAPI 文档
服务治理: 集成 Consul、Nacos 和 etcd，提供开箱即用的服务注册与发现能力
配置中心: 支持通过 Consul、Nacos 或 etcd 进行动态配置管理
数据库集成: 采用 GORM 作为 ORM，支持 MySQL、PostgreSQL 和 SQLite
依赖注入: 使用 Wire 进行依赖注入，清晰化对象之间的依赖关系
通用工具链: 提供 app.mk 通用 Makefile，所有服务共享统一的构建流程
认证鉴权: 内置 JWT 中间件，方便实现用户认证
容器化: 提供 Dockerfile 和 docker-compose.yml，轻松实现容器化部署
可观测性: 已集成 Metrics (Prometheus) 和 Trace (Jaeger) 的基础配置

📖 项目文档

API 文档: 在线文档 - 查看和测试所有 API 接口
项目配置: configs/config.yaml - 完整的配置选项说明

🚀 快速开始

前置要求

Go 1.21 或更高版本
Buf CLI (用于 Protobuf 管理)
Wire (用于依赖注入)
Make 工具

克隆项目

# 克隆项目
git clone https://github.com/horonlee/krathub.git
cd krathub

安装开发工具

# 安装 Kratos CLI
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest

# 安装 Buf CLI
go install github.com/bufbuild/buf/cmd/buf@latest

# 安装 Wire
go install github.com/google/wire/cmd/wire@latest

# 安装其他必要工具
make init

配置项目

# 复制配置示例文件
cp app/krathub/service/configs/config-example.yaml app/krathub/service/configs/config.yaml

# 根据需要修改配置
vim app/krathub/service/configs/config.yaml

生成代码并启动

# 生成所有代码（protobuf、wire、openapi）
make gen

# 构建并运行 krathub 服务
cd app/krathub/service
make run

服务启动后，HTTP 服务将监听在 0.0.0.0:9000，gRPC 服务将监听在 0.0.0.0:9001 (以默认配置为例)。

启动依赖服务

Krathub 需要以下依赖服务：

# 使用 Docker 启动 Redis
docker run -d -p 6379:6379 redis:latest

# 使用 Docker 启动 MySQL（可选，也可以使用 SQLite）
docker run -d -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=krathub \
  mysql:8.0

然后修改配置文件中的数据库和 Redis 连接信息。 vim app/krathub/service/configs/config.yaml


### 生成代码并启动

```shell
# 生成所有代码（protobuf、wire、openapi）
make gen

# 构建并运行 krathub 服务
cd app/krathub/service
make run

服务启动后，HTTP 服务将监听在 0.0.0.0:9000，gRPC 服务将监听在 0.0.0.0:9001 (以默认配置为例)。

📁 项目结构

.
├── api/                          # Protobuf API 定义和生成代码
│   ├── buf.gen.yaml             # Buf 代码生成配置（Go 代码）
│   ├── buf.work.yaml            # Buf workspace 配置
│   ├── buf.{service}.openapi.gen.yaml  # 各服务的 OpenAPI 生成配置
│   ├── gen/                     # 生成的 Go 代码
│   │   └── go/                  # Go protobuf 代码
│   └── protos/                  # Proto 源文件
│       ├── buf.yaml             # Proto 依赖配置
│       ├── conf/v1/             # 配置定义
│       ├── krathub/service/v1/  # Krathub HTTP 接口（i_*.proto）
│       ├── auth/service/v1/     # Auth gRPC 服务
│       ├── user/service/v1/     # User gRPC 服务
│       ├── test/service/v1/     # Test gRPC 服务
│       └── sayhello/service/v1/ # SayHello 独立微服务
│
├── app/                         # 微服务应用目录
│   ├── krathub/service/         # Krathub 主服务
│   │   ├── cmd/server/          # 服务启动入口
│   │   ├── internal/            # 内部实现（不对外暴露）
│   │   │   ├── biz/            # 业务逻辑层
│   │   │   ├── data/           # 数据访问层
│   │   │   ├── server/         # gRPC/HTTP 服务器配置
│   │   │   └── service/        # Service 层实现
│   │   ├── configs/            # 服务配置文件
│   │   ├── bin/                # 编译输出目录
│   │   ├── openapi.yaml        # 生成的 OpenAPI 文档
│   │   └── Makefile            # 服务级 Makefile（include app.mk）
│   │
│   └── sayhello/service/        # SayHello 独立微服务（示例）
│       ├── openapi.yaml        # 生成的 OpenAPI 文档
│       └── Makefile            # 服务级 Makefile
│
├── app.mk                       # 通用服务 Makefile（所有服务共享）
├── Makefile                     # 根目录 Makefile（管理所有服务）
├── pkg/                         # 可在项目内部共享的通用库
├── manifest/                    # 部署相关文件
│   ├── SQL/                    # 数据库脚本
│   ├── docker/                 # Docker 配置
│   └── kubernetes/             # K8s 配置
└── examples/                    # 示例项目

Proto 文件组织规范

项目采用以下 Proto 文件组织规范：

HTTP 接口文件 (i_*.proto)
- 位置：api/protos/krathub/service/v1/i_*.proto
- 包名：统一使用 krathub.service.v1
- 用途：包含 HTTP 注解的接口定义，用于生成 OpenAPI 文档
- 示例：i_auth.proto, i_user.proto, i_test.proto
gRPC 服务文件
- 位置：api/protos/{service}/service/v1/{service}.proto
- 包名：独立包名 {service}.service.v1
- 用途：纯 gRPC 接口定义，不包含 HTTP 注解
- 示例：auth/service/v1/auth.proto, user/service/v1/user.proto
独立微服务
- 位置：api/protos/{service}/service/v1/{service}.proto
- 包名：独立包名 {service}.service.v1
- 用途：完全独立的微服务，可包含 HTTP 注解
- 示例：sayhello/service/v1/sayhello.proto

📝 开发流程

推荐的开发顺序如下，以确保依赖关系正确：

1. 定义 API (`api/protos/`)

在 .proto 文件中定义服务接口：

// HTTP 接口：api/protos/krathub/service/v1/i_example.proto
syntax = "proto3";
package krathub.service.v1;

import "google/api/annotations.proto";

service Example {
  rpc GetExample(GetExampleRequest) returns (GetExampleResponse) {
    option (google.api.http) = {
      get: "/api/v1/example/{id}"
    };
  }
}

2. 生成代码

# 在根目录生成所有 protobuf 代码
make api

# 为所有服务生成 OpenAPI 文档
make openapi

# 或者一次性生成所有代码
make gen

3. 实现业务逻辑

按照 Kratos 的分层架构实现：

业务逻辑层 (internal/biz/): 定义业务接口和实现
数据访问层 (internal/data/): 实现数据持久化
服务层 (internal/service/): 实现 API 接口

4. 依赖注入

在 cmd/server/wire.go 中注册新组件：

//go:build wireinject
// +build wireinject

func wireApp(...) (*kratos.App, func(), error) {
    panic(wire.Build(
        server.ProviderSet,
        data.ProviderSet,
        biz.ProviderSet,
        service.ProviderSet,
        newApp,
    ))
}

生成依赖注入代码：

# 在服务目录下
cd app/krathub/service
make wire

5. 运行和测试

# 在服务目录下运行
cd app/krathub/service
make run

# 或者在根目录构建所有服务
make build

🛠️ 常用命令

根目录命令（管理所有服务）

初始化和设置

make init - 安装所有开发工具（buf, wire, protoc 插件等）
make plugin - 安装 protoc 插件
make cli - 安装 CLI 工具（kratos, buf, wire 等）

代码生成

make api - 生成所有 protobuf Go 代码
make openapi - 为所有服务生成 OpenAPI 文档
make wire - 为所有服务生成 wire 依赖注入代码
make gen - 生成所有代码（api + openapi + wire）

构建和运行

make build - 构建所有服务（包含代码生成）
make build_only - 仅构建所有服务（不生成代码）
make all - 生成并构建所有服务

代码质量

make test - 运行所有测试
make lint - 运行代码检查
make vet - 运行静态分析

其他

make clean - 清理所有构建产物
make docker - 构建所有服务的 Docker 镜像
make env - 显示环境变量
make help - 显示帮助信息

服务级命令（在服务目录下执行）

进入服务目录：cd app/krathub/service

开发命令

make run - 运行服务（包含代码生成）
make build - 构建服务（包含代码生成）
make build_only - 仅构建服务
make app - 生成并构建服务

代码生成

make api - 生成 protobuf 代码
make openapi - 生成 OpenAPI 文档
make wire - 生成 wire 代码
make ent - 生成 ent 代码（如果使用 ent）
make genDao - 生成 GORM GEN 的 PO 和 DAO 代码（如果使用 gorm-gen）
make gen - 生成所有代码

其他

make clean - 清理构建产物
make docker - 构建 Docker 镜像
make env - 显示环境变量

Buf 相关命令

make lint.proto - 检查 proto 文件规范
make buf.update - 更新 buf 依赖

添加新服务

mkdir -p app/newservice/service

创建服务 Makefile：

echo "include ../../../app.mk" > app/newservice/service/Makefile

创建 OpenAPI 生成配置：

# 复制并修改现有配置
cp api/buf.krathub.openapi.gen.yaml api/buf.newservice.openapi.gen.yaml
# 修改配置中的服务名称和路径

定义 proto 文件并生成代码：

# 创建 proto 文件
mkdir -p api/protos/newservice/service/v1
# 编写 proto 文件...

# 生成代码
make api
make openapi

实现服务代码（参考 krathub 服务结构）

根目录的 Makefile 会自动发现并管理新服务！

🗄️ 数据库支持

项目支持多种数据库后端，通过配置文件即可切换：

MySQL (默认) - 企业级关系型数据库
PostgreSQL - 高性能开源关系型数据库
SQLite - 轻量级嵌入式数据库

数据库配置示例请参考 app/krathub/service/configs/config.yaml。

🐳 Docker 支持

项目提供完整的 Docker 支持：

# 构建所有服务的 Docker 镜像
make docker

# 构建单个服务的 Docker 镜像
cd app/krathub/service
make docker

🔧 配置说明

每个服务的配置文件位于 app/{service}/service/configs/config.yaml，支持通过环境变量覆盖默认值。

核心配置项：

服务配置 - HTTP/gRPC 服务地址、TLS 证书等
数据库配置 - 支持 MySQL/PostgreSQL/SQLite
Redis 配置 - 缓存和会话存储
服务治理 - Consul/Nacos/etcd 注册发现
配置中心 - 支持从 Consul/Nacos/etcd 动态加载配置
JWT 认证 - 用户认证和授权
日志配置 - 日志级别、文件轮转等
链路追踪 - Jaeger/Zipkin 配置
监控指标 - Prometheus 配置

完整的配置示例请参考 app/krathub/service/configs/config-example.yaml 文件。

📚 技术栈

框架: Kratos v2 - Go 微服务框架
Protobuf 管理: Buf - 现代化的 Protobuf 工具链
依赖注入: Wire - 编译时依赖注入
ORM: GORM - Go ORM 库
缓存: Redis - 内存数据库
服务发现: Consul / Nacos / etcd
链路追踪: Jaeger / Zipkin
监控: Prometheus + Grafana

🎯 最佳实践

Proto 文件管理

HTTP 接口统一管理: 所有带 HTTP 注解的接口放在 krathub/service/v1/i_*.proto
gRPC 服务独立包: 每个 gRPC 服务使用独立的包名，避免类型冲突
使用 Buf 管理依赖: 通过 buf.build 远程依赖，无需本地 third_party

服务开发

分层架构: 严格遵循 biz -> data -> service 的分层结构
依赖注入: 使用 Wire 管理依赖，保持代码清晰
配置管理: 使用配置中心进行动态配置管理
错误处理: 使用 Kratos 的错误处理机制，统一错误码

代码组织

服务独立: 每个服务在 app/{service}/service 下独立开发
共享代码: 通用代码放在 pkg/ 目录下
配置独立: 每个服务有自己的配置文件
文档自动生成: OpenAPI 文档自动生成到服务目录

📞 客户端层 (Client)

internal/client 是一个自定义的层，用于管理对外部 gRPC 等服务的调用。它提供了一个客户端工厂，可以方便地基于服务发现创建和复用连接，专为服务间的通信而设计。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

在提交 PR 之前，请确保：

代码通过 make lint 检查
所有测试通过 make test
更新相关文档

📄 许可协议

本项目遵循 LICENSE 文件中的许可协议。

Directories ¶

Path	Synopsis
api
gen/go/auth/service/v1
gen/go/conf/v1
gen/go/krathub/service/v1
gen/go/sayhello/service/v1
gen/go/test/service/v1
gen/go/user/service/v1
app
krathub/service/cmd/genDao command
krathub/service/cmd/server command
krathub/service/internal/biz
krathub/service/internal/client
krathub/service/internal/consts
krathub/service/internal/data
krathub/service/internal/data/dao
krathub/service/internal/data/po
krathub/service/internal/server
krathub/service/internal/server/middleware
krathub/service/internal/service
sayhello/service/cmd/server command
sayhello/service/internal/server
sayhello/service/internal/service
pkg
configCenter
hash Package hash 哈希操作类	Package hash 哈希操作类
helpers
jwt
logger
middleware/cors
redis
registry

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

Krathub

✨ 核心特性

📖 项目文档

🚀 快速开始

前置要求

克隆项目

安装开发工具

配置项目

生成代码并启动

启动依赖服务

📁 项目结构

Proto 文件组织规范

📝 开发流程

1. 定义 API (api/protos/)

2. 生成代码

3. 实现业务逻辑

4. 依赖注入

5. 运行和测试

🛠️ 常用命令

根目录命令（管理所有服务）

初始化和设置

代码生成

构建和运行

代码质量

其他

服务级命令（在服务目录下执行）

开发命令

代码生成

其他

Buf 相关命令

添加新服务

🗄️ 数据库支持

🐳 Docker 支持

🔧 配置说明

📚 技术栈

🎯 最佳实践

Proto 文件管理

服务开发

代码组织

📞 客户端层 (Client)

🤝 贡献指南

📄 许可协议

Directories ¶

1. 定义 API (`api/protos/`)