Kiwi User

Kiwi User 是一个基于 Go 语言构建的用户服务微服务，负责用户认证、组织管理、RBAC 权限控制和支付集成等核心功能。项目采用 DDD（领域驱动设计）分层架构，使用 Uber Fx 进行依赖注入。

技术栈

• 语言: Go 1.25
• Web 框架: Gin
• 依赖注入: Uber Fx
• ORM / 数据建模: Ent
• 数据库: PostgreSQL
• 数据库迁移: Atlas
• 缓存: Redis
• 认证: JWT (RSA)
• API 文档: Swagger (swag)
• 可观测性: OpenTelemetry
• 容器化: Docker

项目架构

项目遵循 DDD 分层架构：

kiwi-user/
├── cmd/server/apiserver/    # 应用入口
├── config/                  # 配置定义（API Server、JWT、DB、支付等）
├── build/                   # Dockerfile
├── internal/
│   ├── facade/              # 接口层
│   │   ├── controller/      # API / Admin 控制器
│   │   ├── dto/             # 数据传输对象
│   │   └── server/          # HTTP Server、路由、中间件
│   ├── application/         # 应用层（用例编排）
│   ├── domain/              # 领域层
│   │   ├── model/           # Entity、Aggregate、Enum
│   │   ├── service/         # 领域服务
│   │   └── contract/        # Repository 接口定义
│   ├── infrastructure/      # 基础设施层
│   │   ├── repository/      # Ent Repository 实现
│   │   ├── jwt/             # JWT 工具
│   │   ├── payment/         # 支付集成（Stripe、微信支付）
│   │   └── utils/           # 工具类
│   ├── bootstrap/           # 初始化引导
│   └── constants/           # 常量定义

功能模块

用户认证

支持多种登录方式：

登录方式	接口
微信小程序登录	POST /v1/login/wechat/miniprogram
微信网页登录	POST /v1/login/wechat/web
密码登录	POST /v1/login/password
手机验证码登录	POST /v1/login/phone
邮箱验证码登录	POST /v1/login/email
Google OAuth 登录	POST /v1/login/google/web
组织登录	POST /v1/login/organization

Token 管理

• 验证 Access Token: POST /v1/token/verify
• 刷新 Access Token: POST /v1/token/refresh
• 获取公钥: GET /v1/token/publickey

用户管理

• 获取用户信息: GET /v1/user/info
• 更新用户信息: PUT /v1/user/info
• 用户登出: POST /v1/user/logout

组织管理

• 创建组织: POST /admin/organization
• 更新组织: PUT /admin/organization
• 查询组织列表: GET /admin/organization/infos
• 组织成员管理（增删查）

组织申请

• 用户提交组织申请: POST /v1/user/organization_application/request
• 查看申请列表: GET /v1/user/organization_application/infos
• 管理员审核申请: PUT /admin/organization_application/audit

RBAC 权限控制

• 应用管理（创建、查询、设置默认角色）
• 角色管理
• 权限范围（Scope）管理
• 用户角色分配

支付集成

• 微信支付: 创建支付单、支付回调、状态查询
• Stripe: Checkout Session 创建、Webhook 回调、订阅取消

内部接口

• 批量获取用户公开信息: POST /internal/user/infos
• 批量获取组织信息: POST /internal/organization/infos
• 获取当前登录信息: GET /internal/getCurrentInfos

快速开始

前置要求

• Go 1.25+
• PostgreSQL
• Redis
• Atlas CLI（数据库迁移）

配置

创建配置文件 conf/config.yaml，包含以下配置项：

api_server:
  host: "0.0.0.0"
  port: 8080

postgres:
  connection_string: "postgres://user:password@localhost:5432/kiwi_user?sslmode=disable"

jwt:
  private_key_path: "/path/to/private.pem"
  public_key_path: "/path/to/public.pem"

# redis, wechat, google, stripe, sms, mail, posthog, oss 等配置...

本地运行

# 生成 Ent 代码
make generate-repository-code

# 执行数据库迁移
make apply-migration-repository-db

# 启动服务
go run cmd/server/apiserver/main.go --config.file=conf/config.yaml

Docker 构建

# Staging
export GITHUB_USER=<your-github-user>
export GITHUB_ACCESS_TOKEN=<your-token>
make build-staging-image

# Production
make build-production-image VERSION=v1.0.0

运行测试

make test-unit

API 文档

项目使用 Swagger 生成 API 文档：

make generate-api-swagger

生成后可通过 Swagger UI 查看完整的 API 文档。

数据库迁移

# 生成迁移文件（需要本地 Atlas Dev DB）
make generate-migration-repository-db

# 应用迁移
make apply-migration-repository-db