sdk

IAM SDK for Go

pkg/sdk 是 IAM 的官方 Go 接入入口。当前公开稳定面固定为：

• pkg/sdk
• pkg/sdk/config
• pkg/sdk/auth/client
• pkg/sdk/auth/jwks
• pkg/sdk/auth/verifier
• pkg/sdk/auth/serviceauth
• pkg/sdk/authz
• pkg/sdk/identity
• pkg/sdk/idp
• pkg/sdk/errors

transport、observability 和高级错误分析能力已经收回内部实现，不再作为公开稳定包。

30 秒结论

• 如果你要接 IAM，优先从 sdk.NewClient(...) 开始。
• 如果你只需要认证能力，优先使用 pkg/sdk/auth/client、pkg/sdk/auth/jwks、pkg/sdk/auth/verifier、pkg/sdk/auth/serviceauth。
• 统一错误判断入口是 pkg/sdk/errors，对外只保留 IAMError、Wrap、常用 Is* 谓词、AsIAMError、GRPCCode、Message、ToHTTPStatus。
• 自定义 metrics / tracing 通过 sdk.WithMetricsCollector(...)、sdk.WithTracingHook(...) 注入；是否启用 SDK 内置 observability 链路由 Config.Observability 显式控制。

包结构

pkg/sdk/
├── sdk.go                     # 包说明
├── aliases.go                 # Config / ClientOption 等别名与便捷函数
├── client.go                  # sdk.Client / sdk.NewClient
├── context_helpers.go         # request-id / trace-id helper
├── config/                    # 公开配置定义、加载器、option
├── errors/                    # 公开错误 facade
├── auth/                      # 认证领域子包
│   ├── client/
│   ├── jwks/
│   ├── verifier/
│   └── serviceauth/
├── authz/                     # 授权判定 client
├── identity/                  # 身份 / guardianship client
├── idp/                       # IDP client
├── internal/
│   ├── transport/             # gRPC 连接、重试、metadata、拦截器
│   ├── observability/         # 默认 metrics / tracing / circuit breaker
│   └── errorsx/               # 高级错误分析 / matcher / handler
└── _examples/                 # 完整可运行示例

快速开始

import (
    "context"
    "log"

    authnv1 "github.com/FangcunMount/iam/api/grpc/iam/authn/v1"
    sdk "github.com/FangcunMount/iam/pkg/sdk"
)

func main() {
    ctx := context.Background()

    client, err := sdk.NewClient(ctx, &sdk.Config{
        Endpoint: "localhost:8081",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    resp, err := client.Auth().VerifyToken(ctx, &authnv1.VerifyTokenRequest{
        AccessToken: "jwt-token",
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("valid=%v", resp.GetValid())
}

从环境变量加载：

cfg, err := sdk.ConfigFromEnv()
if err != nil {
    log.Fatal(err)
}

client, err := sdk.NewClient(ctx, cfg)

从 Viper 加载：

import (
    "github.com/spf13/viper"
    "github.com/FangcunMount/iam/pkg/sdk/config"
)

v := viper.New()
v.SetConfigFile("config.yaml")
if err := v.ReadInConfig(); err != nil {
    log.Fatal(err)
}

cfg, err := config.FromViper(v)
if err != nil {
    log.Fatal(err)
}

直接使用认证子包

如果你只需要认证能力，不必创建 sdk.Client：

import (
    authclient "github.com/FangcunMount/iam/pkg/sdk/auth/client"
    authjwks "github.com/FangcunMount/iam/pkg/sdk/auth/jwks"
    authserviceauth "github.com/FangcunMount/iam/pkg/sdk/auth/serviceauth"
    authverifier "github.com/FangcunMount/iam/pkg/sdk/auth/verifier"
)

_ = authclient.NewClient
_ = authjwks.NewJWKSManager
_ = authverifier.NewTokenVerifier
_ = authserviceauth.NewServiceAuthHelper

JWT 本地验证

import (
    sdk "github.com/FangcunMount/iam/pkg/sdk"
    authjwks "github.com/FangcunMount/iam/pkg/sdk/auth/jwks"
    authverifier "github.com/FangcunMount/iam/pkg/sdk/auth/verifier"
)

jwksManager, err := authjwks.NewJWKSManager(
    &sdk.JWKSConfig{
        URL:             "https://iam.example.com/.well-known/jwks.json",
        RefreshInterval: 5 * time.Minute,
    },
    authjwks.WithCacheEnabled(true),
    authjwks.WithAuthClient(client.Auth()),
)
if err != nil {
    log.Fatal(err)
}
defer jwksManager.Stop()

verifier, err := authverifier.NewTokenVerifier(
    &sdk.TokenVerifyConfig{
        AllowedAudience: []string{"my-app"},
        AllowedIssuer:   "https://iam.example.com",
    },
    jwksManager,
    client.Auth(),
)
if err != nil {
    log.Fatal(err)
}

result, err := verifier.Verify(ctx, token, nil)
if err != nil {
    log.Fatal(err)
}
log.Printf("user=%s session=%s", result.Claims.UserID, result.Claims.SessionID)

服务间认证

import (
    sdk "github.com/FangcunMount/iam/pkg/sdk"
    authserviceauth "github.com/FangcunMount/iam/pkg/sdk/auth/serviceauth"
)

helper, err := authserviceauth.NewServiceAuthHelper(&sdk.ServiceAuthConfig{
    ServiceID:      "qs-service",
    TargetAudience: []string{"iam-service"},
    TokenTTL:       time.Hour,
    RefreshBefore:  5 * time.Minute,
}, client.Auth())
if err != nil {
    log.Fatal(err)
}
defer helper.Stop()

authCtx, err := helper.NewAuthenticatedContext(ctx)
if err != nil {
    log.Fatal(err)
}

_, err = client.Identity().GetUser(authCtx, "user-123")

错误处理

import sdkerrors "github.com/FangcunMount/iam/pkg/sdk/errors"

resp, err := client.Identity().GetUser(ctx, "user-123")
if err != nil {
    switch {
    case sdkerrors.IsNotFound(err):
        log.Println("用户不存在")
    case sdkerrors.IsUnauthorized(err):
        log.Println("未认证")
    case sdkerrors.IsPermissionDenied(err):
        log.Println("权限不足")
    case sdkerrors.IsRetryable(err):
        log.Println("可重试错误")
    default:
        log.Printf("grpc=%s http=%d msg=%s", sdkerrors.GRPCCode(err), sdkerrors.ToHTTPStatus(err), sdkerrors.Message(err))
    }
    return
}

_ = resp

如果需要拿到结构化错误：

import sdkerrors "github.com/FangcunMount/iam/pkg/sdk/errors"

if iamErr, ok := sdkerrors.AsIAMError(err); ok {
    log.Printf("code=%s grpc=%s msg=%s", iamErr.Code, iamErr.GRPCCode, iamErr.Message)
}

Metrics 与 Tracing Hook

SDK 的 request-id / metrics / tracing / circuit breaker 链路已经内聚到 pkg/sdk/internal/...，但默认不会自动启用。只有显式设置 Config.Observability 时，SDK 才会挂载对应默认拦截器；对外仍只保留 hook 注入点。

import (
    "context"
    "time"

    sdk "github.com/FangcunMount/iam/pkg/sdk"
)

type myMetrics struct{}

func (m *myMetrics) RecordRequest(method, code string, duration time.Duration) {}

type myTracing struct{}

func (t *myTracing) StartSpan(ctx context.Context, name string) (context.Context, func()) {
    return ctx, func() {}
}

func (t *myTracing) SetAttributes(context.Context, map[string]string) {}
func (t *myTracing) RecordError(context.Context, error) {}

client, err := sdk.NewClient(ctx, &sdk.Config{
    Endpoint:      "iam.example.com:8081",
    Observability: sdk.DefaultObservabilityConfig(),
}, sdk.WithMetricsCollector(&myMetrics{}), sdk.WithTracingHook(&myTracing{}))

设计亮点

迁移说明

这轮 SDK 重构包含 breaking change：

• pkg/sdk/transport 已删除
• pkg/sdk/observability 已删除
• pkg/sdk/errors 的高级分析 / matcher / handler API 已收回内部

替代入口见 07-migration-breaking-changes.md。

文档

示例