yvan
/
kra-new
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

优化结构

This commit is contained in:
Yvan 2026-08-24 20:12:41 +08:00
parent 7643152c1e
commit d3c20c578f
9 changed files with 197 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
AGENTS.md
View File

@ -18,7 +18,6 @@ internal/data/ Repo implementations, database clients, migrations.
internal/initialize/ First-install and configuration orchestration.
internal/integration/ External I/O adapters: cache, email, payment, storage.
internal/logging/ Application logging infrastructure.
internal/security/ Security mechanisms such as admin JWT handling.
internal/utils/ Stateless, internal-only helper packages.
```

6
docs/system-pkg-audit.md
View File

@ -29,10 +29,9 @@
- `biz/integration`：支付/消息队列/WebSocket 集成配置定义与校验。
- `biz/task`：定时任务模型、任务用例和任务注册协议。
- `conf`：system 配置 proto、运行时快照和生成代码。
- `data`：共享数据库生命周期与配置 watcher；PO/仓储按 `system`、`integration`、`task`、`payment` 子包隔离。
- `data`：共享数据库生命周期与配置 watcher；PO/仓储按 `system`、`integration`、`task`、`payment` 子包隔离；后台 JWT claims 与签发/解析位于 `data/system/token.go`。
- `initialize`：首次安装、配置迁移、种子编排和运行时重载。
- `integration`：Redis、邮件、存储、支付、WebSocket、EMQX 和 RabbitMQ 的 provider 生命周期。
- `security`：JWT claims、签发/解析和后台安全实现。
- `routecatalog`：HTTP 公开性、操作审计、请求体策略和 API 分组/说明的统一目录。
- `service`：HTTP DTO（`service/dto`）、DTO 与 DO 转换和应用服务。
- `server`：Gin 生命周期；handler、middleware、router、HTTP 适配按子包维护。
@ -55,13 +54,12 @@ internal/
config/ # Viper 配置、快照和热更新
global/ # 进程级共享资源入口
data/
system/ # 系统表与系统仓储
system/ # 系统表与系统仓储，含后台 JWT token.go
integration/# 集成配置表与仓储
task/ # 定时任务表与仓储
payment/ # 支付表与仓储
initialize/ # 首次安装和配置编排
integration/ # 外部 I/O provider
security/ # JWT 和安全实现
server/ # Gin 生命周期，内部按 handler/middleware/router/httpx 分类
service/ # 应用服务；DTO 集中在 dto 子包
worker/ # 任务运行时

3
internal/README.md
View File

@ -15,7 +15,6 @@
- `initialize`：数据库首次初始化和系统种子数据编排
- `integration`：Redis、邮件、对象存储、支付、WebSocket、EMQX 和 RabbitMQ 适配器
- `routecatalog`：统一声明 HTTP 路由的公开性、操作审计、请求体策略和 API 元数据
- `security`：后台 JWT 等安全实现
- `server`：Gin server 组合与生命周期；横切 HTTP 代码按子包维护：
`server/handler`、`server/middleware`、`server/router`、`server/staticfiles`；
通用响应和 Cookie 工具位于 `pkg/httpx`
@ -26,7 +25,7 @@
目录代表边界，模块文件按资源命名。DTO、handler、中间件、路由和 HTTP
响应工具分别放在独立子包中，避免 `service`/`server` 根目录堆积几十个
文件，同时不把只有一两个文件的业务逻辑再拆成新包。system 的 module
定义位于 `modules/system`，JWT 实现集中在 `security`，protobuf JSON 统一使用
定义位于 `modules/system`，后台 JWT 签发/解析位于 `data/system/token.go`，protobuf JSON 统一使用
`pkg/protoutil`。
`internal/modules/catalog.go` 是静态模块 catalog 的唯一注册点，负责按依赖顺序

24
internal/data/system/runtime.go
View File

@ -8,7 +8,6 @@ import (
"time"
"kra/internal/config"
"kra/internal/security"
jwt "github.com/golang-jwt/jwt/v5"
)
@ -95,7 +94,7 @@ func (i *tokenIssuer) IssueToken(user *system.User, authorityID uint, mustChange
if user.PasswordUpdatedAt != nil {
passwordVersion = user.PasswordUpdatedAt.UnixNano()
}
token, claims, err := security.Generate(settings.SigningKey, settings.Issuer, expires, settings.Buffer, user.ID, authorityID, user.UUID, user.Username, user.NickName, mustChangePassword, passwordVersion)
token, claims, err := generateToken(settings.SigningKey, settings.Issuer, expires, settings.Buffer, user.ID, authorityID, user.UUID, user.Username, user.NickName, mustChangePassword, passwordVersion)
if err != nil {
return nil, err
}
@ -107,16 +106,16 @@ func (i *tokenIssuer) ReissueToken(source *system.AuthClaims, authorityID uint)
return nil, errors.New("nil JWT claims")
}
settings := i.settings.JWTSettings()
claims := &security.Claims{
claims := &tokenClaims{
UUID: source.UUID, ID: source.ID, Username: source.Username, NickName: source.NickName,
AuthorityID: authorityID, BufferTime: int64(source.BufferTime / time.Second), UserType: source.UserType,
MustChangePwd: source.MustChangePwd, PasswordVersion: source.PasswordVersion,
RegisteredClaims: jwt.RegisteredClaims{
Audience: jwt.ClaimStrings{security.TokenAudience}, Issuer: settings.Issuer,
Audience: jwt.ClaimStrings{tokenAudience}, Issuer: settings.Issuer,
IssuedAt: jwt.NewNumericDate(source.IssuedAt), NotBefore: jwt.NewNumericDate(source.NotBefore), ExpiresAt: jwt.NewNumericDate(source.ExpiresAt),
},
}
token, err := security.Sign(settings.SigningKey, claims)
token, err := signToken(settings.SigningKey, claims)
if err != nil {
return nil, err
}
@ -125,20 +124,9 @@ func (i *tokenIssuer) ReissueToken(source *system.AuthClaims, authorityID uint)
func (i *tokenIssuer) ParseToken(token string) (*system.AuthClaims, error) {
settings := i.settings.JWTSettings()
claims, err := security.ParseWithIssuer(token, settings.SigningKey, settings.Issuer)
claims, err := parseTokenWithIssuer(token, settings.SigningKey, settings.Issuer)
if err != nil {
switch {
case errors.Is(err, security.ErrTokenExpired):
return nil, system.ErrTokenExpired
case errors.Is(err, security.ErrTokenMalformed):
return nil, system.ErrTokenMalformed
case errors.Is(err, security.ErrTokenSignatureInvalid):
return nil, system.ErrTokenSignatureInvalid
case errors.Is(err, security.ErrTokenNotValidYet):
return nil, system.ErrTokenNotValidYet
default:
return nil, system.ErrTokenInvalid
}
return nil, err
}
audience := append([]string(nil), claims.Audience...)
issuedAt := time.Time{}

111
internal/data/system/token.go Normal file
View File

@ -0,0 +1,111 @@
package system
import (
"errors"
"kra/internal/biz/system"
"time"
jwt "github.com/golang-jwt/jwt/v5"
)
// tokenAudience is the KRA administrator audience claim. Claims, audience,
// issuer and password-version fields are this application's security
// protocol, so they stay beside the only issuer that signs them.
const tokenAudience = "KRA"
var (
errEmptySigningKey = errors.New("empty JWT signing key")
errInvalidClaims = errors.New("invalid token claims")
)
type tokenClaims struct {
UUID string
ID uint
Username string
NickName string
AuthorityID uint `json:"AuthorityId"`
BufferTime int64
UserType string
MustChangePwd bool `json:"mustChangePwd"`
PasswordVersion int64 `json:"passwordVersion,omitempty"`
jwt.RegisteredClaims
}
func generateToken(secret, issuer string, expires, buffer time.Duration, userID, authorityID uint, uuid, username, nickname string, mustChange bool, passwordVersion int64) (string, *tokenClaims, error) {
if err := validateSigningOptions(secret, expires, buffer); err != nil {
return "", nil, err
}
now := time.Now()
claims := &tokenClaims{UUID: uuid, ID: userID, Username: username, NickName: nickname, AuthorityID: authorityID, BufferTime: int64(buffer / time.Second), UserType: "admin", MustChangePwd: mustChange, PasswordVersion: passwordVersion, RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{tokenAudience}, Issuer: issuer, IssuedAt: jwt.NewNumericDate(now), NotBefore: jwt.NewNumericDate(now.Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(now.Add(expires))}}
token, err := signToken(secret, claims)
return token, claims, err
}
func signToken(secret string, claims *tokenClaims) (string, error) {
if secret == "" {
return "", errEmptySigningKey
}
if claims == nil {
return "", errInvalidClaims
}
return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(secret))
}
// parseTokenWithIssuer validates a KRA admin token and maps driver errors to
// the biz token errors callers above already branch on.
func parseTokenWithIssuer(tokenString, secret, issuer string) (*tokenClaims, error) {
if secret == "" {
return nil, errEmptySigningKey
}
options := []jwt.ParserOption{
jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}),
jwt.WithAudience(tokenAudience),
jwt.WithExpirationRequired(),
jwt.WithNotBeforeRequired(),
jwt.WithLeeway(time.Second),
}
if issuer != "" {
options = append(options, jwt.WithIssuer(issuer))
}
token, err := jwt.ParseWithClaims(tokenString, &tokenClaims{}, func(token *jwt.Token) (any, error) {
if token.Method != jwt.SigningMethodHS256 {
return nil, errors.New("unexpected signing method")
}
return []byte(secret), nil
}, options...)
if err != nil {
switch {
case errors.Is(err, jwt.ErrTokenExpired):
return nil, system.ErrTokenExpired
case errors.Is(err, jwt.ErrTokenMalformed):
return nil, system.ErrTokenMalformed
case errors.Is(err, jwt.ErrTokenSignatureInvalid):
return nil, system.ErrTokenSignatureInvalid
case errors.Is(err, jwt.ErrTokenNotValidYet):
return nil, system.ErrTokenNotValidYet
default:
return nil, system.ErrTokenInvalid
}
}
if !token.Valid {
return nil, system.ErrTokenInvalid
}
claims, ok := token.Claims.(*tokenClaims)
if !ok {
return nil, system.ErrTokenInvalid
}
return claims, nil
}
func validateSigningOptions(secret string, expires, buffer time.Duration) error {
if secret == "" {
return errEmptySigningKey
}
if expires <= 0 {
return errors.New("JWT expiration must be positive")
}
if buffer < 0 {
return errors.New("JWT buffer must not be negative")
}
return nil
}

77
internal/data/system/token_test.go Normal file
View File

@ -0,0 +1,77 @@
package system
import (
"errors"
"testing"
"time"
"kra/internal/biz/system"
jwt "github.com/golang-jwt/jwt/v5"
)
func TestGenerateAndParseWithIssuerRoundTrip(t *testing.T) {
token, want, err := generateToken("secret", "kra-admin", time.Hour, time.Minute, 7, 8, "uuid", "alice", "Alice", true, 9)
if err != nil {
t.Fatal(err)
}
got, err := parseTokenWithIssuer(token, "secret", "kra-admin")
if err != nil {
t.Fatal(err)
}
if got.ID != want.ID || got.Username != want.Username || got.Audience[0] != tokenAudience {
t.Fatalf("claims = %#v, want %#v", got, want)
}
}
func TestParseRejectsWrongIssuerAndAudience(t *testing.T) {
token, _, err := generateToken("secret", "kra-admin", time.Hour, time.Minute, 1, 1, "uuid", "user", "", false, 0)
if err != nil {
t.Fatal(err)
}
if _, err = parseTokenWithIssuer(token, "secret", "other"); !errors.Is(err, system.ErrTokenInvalid) {
t.Fatalf("wrong issuer error = %v, want ErrTokenInvalid", err)
}
claims := &tokenClaims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{"other"}, Issuer: "kra-admin", IssuedAt: jwt.NewNumericDate(time.Now()), NotBefore: jwt.NewNumericDate(time.Now().Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour))}}
token, err = signToken("secret", claims)
if err != nil {
t.Fatal(err)
}
if _, err = parseTokenWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, system.ErrTokenInvalid) {
t.Fatalf("wrong audience error = %v, want ErrTokenInvalid", err)
}
}
func TestParseRejectsMissingRequiredTimeClaims(t *testing.T) {
claims := &tokenClaims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{tokenAudience}, Issuer: "kra-admin"}}
token, err := signToken("secret", claims)
if err != nil {
t.Fatal(err)
}
if _, err = parseTokenWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, system.ErrTokenInvalid) {
t.Fatalf("missing time claims error = %v, want ErrTokenInvalid", err)
}
}
func TestSigningOptionsRejectInvalidValues(t *testing.T) {
if _, _, err := generateToken("", "kra", time.Hour, 0, 1, 1, "", "", "", false, 0); !errors.Is(err, errEmptySigningKey) {
t.Fatalf("empty key error = %v", err)
}
if _, _, err := generateToken("secret", "kra", 0, 0, 1, 1, "", "", "", false, 0); err == nil {
t.Fatal("zero expiration was accepted")
}
if _, err := signToken("secret", nil); !errors.Is(err, errInvalidClaims) {
t.Fatalf("nil claims error = %v", err)
}
}
func TestParseRejectsAlgorithmConfusion(t *testing.T) {
claims := &tokenClaims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{tokenAudience}, Issuer: "kra-admin", IssuedAt: jwt.NewNumericDate(time.Now()), NotBefore: jwt.NewNumericDate(time.Now().Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour))}}
token, err := jwt.NewWithClaims(jwt.SigningMethodHS512, claims).SignedString([]byte("secret"))
if err != nil {
t.Fatal(err)
}
if _, err = parseTokenWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, system.ErrTokenSignatureInvalid) {
t.Fatalf("algorithm confusion error = %v, want ErrTokenSignatureInvalid", err)
}
}

9
internal/security/README.md
View File

@ -1,9 +0,0 @@
# Internal Security
This package owns the application's administrator JWT policy. It is kept
inside `internal` because its claims, audience, issuer and password-version
fields are KRA-specific security protocol, not a reusable JWT utility.
Generic stateless helpers may live in `pkg`, but admin token signing and
verification stay here so other services cannot accidentally depend on this
application's security contract.

119
internal/security/token.go
View File

@ -1,119 +0,0 @@
package security
import (
"errors"
"time"
"github.com/golang-jwt/jwt/v5"
)
const TokenAudience = "KRA"
var (
ErrEmptySigningKey = errors.New("empty JWT signing key")
ErrInvalidClaims = errors.New("invalid token claims")
ErrTokenExpired = errors.New("token expired")
ErrTokenMalformed = errors.New("token malformed")
ErrTokenSignatureInvalid = errors.New("token signature invalid")
ErrTokenNotValidYet = errors.New("token not valid yet")
ErrTokenInvalid = errors.New("token invalid")
)
type Claims struct {
UUID string
ID uint
Username string
NickName string
AuthorityID uint `json:"AuthorityId"`
BufferTime int64
UserType string
MustChangePwd bool `json:"mustChangePwd"`
PasswordVersion int64 `json:"passwordVersion,omitempty"`
jwt.RegisteredClaims
}
func Generate(secret, issuer string, expires, buffer time.Duration, userID, authorityID uint, uuid, username, nickname string, mustChange bool, passwordVersion int64) (string, *Claims, error) {
if err := validateSigningOptions(secret, expires, buffer); err != nil {
return "", nil, err
}
now := time.Now()
claims := &Claims{UUID: uuid, ID: userID, Username: username, NickName: nickname, AuthorityID: authorityID, BufferTime: int64(buffer / time.Second), UserType: "admin", MustChangePwd: mustChange, PasswordVersion: passwordVersion, RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{TokenAudience}, Issuer: issuer, IssuedAt: jwt.NewNumericDate(now), NotBefore: jwt.NewNumericDate(now.Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(now.Add(expires))}}
token, err := Sign(secret, claims)
return token, claims, err
}
func Sign(secret string, claims *Claims) (string, error) {
if secret == "" {
return "", ErrEmptySigningKey
}
if claims == nil {
return "", ErrInvalidClaims
}
return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(secret))
}
func Parse(tokenString, secret string) (*Claims, error) {
return parse(tokenString, secret, "")
}
// ParseWithIssuer validates a KRA admin token and its configured issuer.
func ParseWithIssuer(tokenString, secret, issuer string) (*Claims, error) {
return parse(tokenString, secret, issuer)
}
func parse(tokenString, secret, issuer string) (*Claims, error) {
if secret == "" {
return nil, ErrEmptySigningKey
}
options := []jwt.ParserOption{
jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}),
jwt.WithAudience(TokenAudience),
jwt.WithExpirationRequired(),
jwt.WithNotBeforeRequired(),
jwt.WithLeeway(time.Second),
}
if issuer != "" {
options = append(options, jwt.WithIssuer(issuer))
}
token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (any, error) {
if token.Method != jwt.SigningMethodHS256 {
return nil, errors.New("unexpected signing method")
}
return []byte(secret), nil
}, options...)
if err != nil {
switch {
case errors.Is(err, jwt.ErrTokenExpired):
return nil, ErrTokenExpired
case errors.Is(err, jwt.ErrTokenMalformed):
return nil, ErrTokenMalformed
case errors.Is(err, jwt.ErrTokenSignatureInvalid):
return nil, ErrTokenSignatureInvalid
case errors.Is(err, jwt.ErrTokenNotValidYet):
return nil, ErrTokenNotValidYet
default:
return nil, ErrTokenInvalid
}
}
if !token.Valid {
return nil, ErrTokenInvalid
}
claims, ok := token.Claims.(*Claims)
if !ok {
return nil, ErrInvalidClaims
}
return claims, nil
}
func validateSigningOptions(secret string, expires, buffer time.Duration) error {
if secret == "" {
return ErrEmptySigningKey
}
if expires <= 0 {
return errors.New("JWT expiration must be positive")
}
if buffer < 0 {
return errors.New("JWT buffer must not be negative")
}
return nil
}

75
internal/security/token_test.go
View File

@ -1,75 +0,0 @@
package security
import (
"errors"
"testing"
"time"
"github.com/golang-jwt/jwt/v5"
)
func TestGenerateAndParseWithIssuerRoundTrip(t *testing.T) {
token, want, err := Generate("secret", "kra-admin", time.Hour, time.Minute, 7, 8, "uuid", "alice", "Alice", true, 9)
if err != nil {
t.Fatal(err)
}
got, err := ParseWithIssuer(token, "secret", "kra-admin")
if err != nil {
t.Fatal(err)
}
if got.ID != want.ID || got.Username != want.Username || got.Audience[0] != TokenAudience {
t.Fatalf("claims = %#v, want %#v", got, want)
}
}
func TestParseRejectsWrongIssuerAndAudience(t *testing.T) {
token, _, err := Generate("secret", "kra-admin", time.Hour, time.Minute, 1, 1, "uuid", "user", "", false, 0)
if err != nil {
t.Fatal(err)
}
if _, err = ParseWithIssuer(token, "secret", "other"); !errors.Is(err, ErrTokenInvalid) {
t.Fatalf("wrong issuer error = %v, want ErrTokenInvalid", err)
}
claims := &Claims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{"other"}, Issuer: "kra-admin", IssuedAt: jwt.NewNumericDate(time.Now()), NotBefore: jwt.NewNumericDate(time.Now().Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour))}}
token, err = Sign("secret", claims)
if err != nil {
t.Fatal(err)
}
if _, err = ParseWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, ErrTokenInvalid) {
t.Fatalf("wrong audience error = %v, want ErrTokenInvalid", err)
}
}
func TestParseRejectsMissingRequiredTimeClaims(t *testing.T) {
claims := &Claims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{TokenAudience}, Issuer: "kra-admin"}}
token, err := Sign("secret", claims)
if err != nil {
t.Fatal(err)
}
if _, err = ParseWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, ErrTokenInvalid) {
t.Fatalf("missing time claims error = %v, want ErrTokenInvalid", err)
}
}
func TestSigningOptionsRejectInvalidValues(t *testing.T) {
if _, _, err := Generate("", "kra", time.Hour, 0, 1, 1, "", "", "", false, 0); !errors.Is(err, ErrEmptySigningKey) {
t.Fatalf("empty key error = %v", err)
}
if _, _, err := Generate("secret", "kra", 0, 0, 1, 1, "", "", "", false, 0); err == nil {
t.Fatal("zero expiration was accepted")
}
if _, err := Sign("secret", nil); !errors.Is(err, ErrInvalidClaims) {
t.Fatalf("nil claims error = %v", err)
}
}
func TestParseRejectsAlgorithmConfusion(t *testing.T) {
claims := &Claims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{TokenAudience}, Issuer: "kra-admin", IssuedAt: jwt.NewNumericDate(time.Now()), NotBefore: jwt.NewNumericDate(time.Now().Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour))}}
token, err := jwt.NewWithClaims(jwt.SigningMethodHS512, claims).SignedString([]byte("secret"))
if err != nil {
t.Fatal(err)
}
if _, err = ParseWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, ErrTokenSignatureInvalid) {
t.Fatalf("algorithm confusion error = %v, want ErrTokenSignatureInvalid", err)
}
}