跳至内容

authx

authx

authx 是一个面向多场景（HTTP / gRPC / CLI）的 Go 认证与鉴权抽象库。

核心原则：

  • 认证与鉴权分离：Check / Can
  • 不绑定认证方式：JWT / 密码 / 短信验证码等都可扩展
  • 核心层保持框架无关，适配层按场景集成

Roadmap

核心 API

  • Engine: 认证与鉴权编排入口
  • ProviderManager: 多 credential 类型 provider 管理器
  • AuthenticationProvider[C]: 认证提供者泛型抽象
  • Authorizer: 鉴权决策接口
  • Check(ctx, credential): 认证
  • Can(ctx, AuthorizationModel): 鉴权
  • Hook: Check/Can 前后切面扩展

快速开始（Core） 

engine := authx.NewEngine(
    authx.WithAuthenticationManager(
        authx.NewProviderManager(
            authx.NewAuthenticationProviderFunc(func(
                _ context.Context,
                in UsernamePassword,
            ) (authx.AuthenticationResult, error) {
                // verify credential
                return authx.AuthenticationResult{
                    Principal: authx.Principal{ID: in.Username},
                }, nil
            }),
        ),
    ),
    authx.WithAuthorizer(authx.AuthorizerFunc(func(
        _ context.Context,
        model authx.AuthorizationModel,
    ) (authx.Decision, error) {
        return authx.Decision{Allowed: true}, nil
    })),
)

result, err := engine.Check(ctx, UsernamePassword{Username: "alice", Password: "secret"})
if err != nil {
    panic(err)
}

decision, err := engine.Can(ctx, authx.AuthorizationModel{
    Principal: result.Principal,
    Action:    "query",
    Resource:  "order",
})
if err != nil {
    panic(err)
}
_ = decision

HTTP 集成

authx/http 提供统一 Guard 与框架中间件：

  • authx/http/std
  • authx/http/gin
  • authx/http/echo
  • authx/http/fiber

统一扩展点：

  • WithCredentialResolverFunc
  • WithAuthorizationResolverFunc
guard := authhttp.NewGuard(
    engine,
    authhttp.WithCredentialResolverFunc(resolveCredential),
    authhttp.WithAuthorizationResolverFunc(resolveAuthorization),
)

router.Use(authstd.Require(guard))
// 高性能路径：router.Use(authstd.RequireFast(guard))

示例

  • authx/http/examples/shared
  • authx/http/examples/jwt
  • authx/http/examples/std
  • authx/http/examples/gin
  • authx/http/examples/echo
  • authx/http/examples/fiber

测试与基准 

go test ./authx/...

# core
go test ./authx -run ^$ -bench BenchmarkEngine -benchmem

# middleware
go test ./authx/http/std -run ^$ -bench BenchmarkRequire -benchmem
go test ./authx/http/gin -run ^$ -bench BenchmarkRequire -benchmem
go test ./authx/http/echo -run ^$ -bench BenchmarkRequire -benchmem
go test ./authx/http/fiber -run ^$ -bench BenchmarkRequire -benchmem