sdk

IAM SDK for Go

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

• pkg/sdk
• pkg/sdk/config
• pkg/sdk/auth/client
• pkg/sdk/auth/challenge
• pkg/sdk/auth/jwks
• pkg/sdk/auth/loginidentity
• pkg/sdk/auth/loginv2
• pkg/sdk/auth/verifier
• pkg/sdk/auth/serviceauth
• pkg/sdk/auth/signup
• 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/                      # 认证领域子包
│   ├── challenge/
│   ├── client/
│   ├── jwks/
│   ├── loginidentity/
│   ├── loginv2/
│   ├── signup/
│   ├── verifier/
│   └── serviceauth/
├── authz/                     # 授权判定 client
├── identity/                  # 身份 / profile / profile-link client
├── idp/                       # IDP client
├── internal/
│   ├── transport/             # gRPC 连接、重试、metadata、拦截器
│   ├── observability/         # 默认 metrics / tracing / circuit breaker
│   └── errorsx/               # 高级错误分析 / matcher / handler
└── _examples/                 # 完整可运行示例

快速开始

import (
    "context"
    "log"

    authnv2 "github.com/FangcunMount/iam/v2/api/grpc/iam/authn/v2"
    sdk "github.com/FangcunMount/iam/v2/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, &authnv2.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/v2/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/v2/pkg/sdk/auth/client"
    authjwks "github.com/FangcunMount/iam/v2/pkg/sdk/auth/jwks"
    authloginidentity "github.com/FangcunMount/iam/v2/pkg/sdk/auth/loginidentity"
    authloginv2 "github.com/FangcunMount/iam/v2/pkg/sdk/auth/loginv2"
    authserviceauth "github.com/FangcunMount/iam/v2/pkg/sdk/auth/serviceauth"
    authsignup "github.com/FangcunMount/iam/v2/pkg/sdk/auth/signup"
    authverifier "github.com/FangcunMount/iam/v2/pkg/sdk/auth/verifier"
)

_ = authclient.NewClient
_ = authjwks.NewJWKSManager
_ = authloginidentity.NewClient
_ = authloginv2.NewClient
_ = authsignup.NewClient
_ = authverifier.NewTokenVerifier
_ = authserviceauth.NewServiceAuthHelper

JWT 本地验证

import (
    sdk "github.com/FangcunMount/iam/v2/pkg/sdk"
    authjwks "github.com/FangcunMount/iam/v2/pkg/sdk/auth/jwks"
    authverifier "github.com/FangcunMount/iam/v2/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/v2/pkg/sdk"
    authserviceauth "github.com/FangcunMount/iam/v2/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")

Identity / Profile 拆分式客户端

统一入口 sdk.Client 会复用同一个 gRPC connection，并暴露三个拆分式 identity 子客户端：

identityClient := client.Identity()       // User / IdentityRead / IdentityLifecycle
profileClient := client.Profile()         // ProfileCommand
profileLinkClient := client.ProfileLink() // ProfileLinkQuery / ProfileLinkCommand

创建档案走 Profile()，不是 Identity()：

resp, err := profileClient.CreateProfile(ctx, &identityv2.CreateProfileRequest{
    UserId:       "1001",
    LegalName:   "小明",
    Gender:      identityv2.Gender_GENDER_MALE,
    Dob:         "2018-01-01",
    IdCardNumber: "",
    Relation:    identityv2.ProfileLinkRelation_PROFILE_LINK_RELATION_PARENT,
})

如果调用方已经持有 gRPC 连接，可以只使用 pkg/sdk/identity 子包：

identityClient := identity.NewClientFromConn(conn)
profileClient := identity.NewProfileClientFromConn(conn)
profileLinkClient := identity.NewProfileLinkClientFromConn(conn)

需要显式注入 generated gRPC client 或测试替身时，保留原始工厂：

profileClient := identity.NewProfileClient(
    identityv2.NewProfileCommandClient(conn),
)

错误处理

import sdkerrors "github.com/FangcunMount/iam/v2/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/v2/pkg/sdk/errors"

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

服务端 V2 gRPC 错误映射已经统一：常见业务错误会稳定落到 InvalidArgument、Unauthenticated、PermissionDenied、NotFound、AlreadyExists、FailedPrecondition、ResourceExhausted、Unavailable、DeadlineExceeded 或 Internal。SDK 调用方不要解析错误消息文本。

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/v2/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 已收回内部
• pkg/sdk/auth/loginv2 是 REST AuthN v2 显式登录入口；pkg/sdk/auth/client 已对齐 gRPC v2 Login/token/JWKS/onboarding 契约
• pkg/sdk/idp 已对齐 v2 WeChat app 查询与 access token 获取/刷新契约
• pkg/sdk/identity 保持拆分式客户端：Client、ProfileClient、ProfileLinkClient；ProfileLink 查询支持 include_revoked

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

文档

示例