开放API与第三方集成模块

openapi-gateway/
├── go.mod
├── cmd/gateway/main.go               # 进程入口：OAuth2 / 路由 / 限流 / 熔断装配
├── deploy/
│   ├── gateway-deployment.yaml       # API 网关 Deployment
│   ├── gateway-ingress.yaml          # Ingress（生产 HTTPS 外部入口）
│   ├── gateway-ratelimit.yaml        # 限流 / 熔断阈值 ConfigMap
│   ├── webhook-receiver-rbac.yaml    # Webhook 接收 SA + Role
│   └── gateway-prometheus.yaml       # ServiceMonitor + 告警规则
├── sdk/go/paas/client.go             # Go SDK 调用示例
└── internal/
    ├── auth/
    │   ├── jwt.go                     # JWT 签发 / 校验 / 作用域
    │   ├── oauth2.go                  # 客户端凭证模式 Token 端点
    │   └── signature.go               # HMAC 请求 / 回调签名校验
    ├── middleware/
    │   ├── auth.go                    # 鉴权中间件（JWT + HMAC 签名）
    │   └── ratelimit.go               # 速率限制 + 熔断中间件
    ├── k8s/
    │   └── gateway.go                 # client-go 经网关（受限角色）
    ├── webhook/
    │   └── dispatch.go                # 事件分发 + 重试 + 死信队列
    ├── metrics/
    │   └── metrics.go                 # Prometheus 指标
    └── api/
        └── handler.go                 # gin 开放 API（配额查询 / Webhook 订阅）

// file: go.mod
module github.com/example/paas/openapi

go 1.22

require (
	github.com/gin-gonic/gin v1.10.0
	github.com/golang-jwt/jwt/v5 v5.2.1
	github.com/prometheus/client_golang v1.19.1
	github.com/sony/gobreaker v0.5.0
	golang.org/x/time v0.5.0
	k8s.io/api v0.30.2
	k8s.io/apimachinery v0.30.2
	k8s.io/client-go v0.30.2
)

# file: deploy/gateway-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: openapi-gateway
  namespace: paas-system
  labels:
    app: openapi-gateway
    tenant: platform
    env: prod
    cluster: prod-cluster
spec:
  replicas: 3
  selector:
    matchLabels:
      app: openapi-gateway
  template:
    metadata:
      labels:
        app: openapi-gateway
        tenant: platform
        env: prod
        cluster: prod-cluster
    spec:
      serviceAccountName: openapi-gateway
      containers:
        - name: gateway
          image: registry.paas.internal/openapi-gateway:v2.3.0
          ports:
            - containerPort: 8081
              name: http
            - containerPort: 9090
              name: metrics
          envFrom:
            - configMapRef:
                name: openapi-gateway-config
          env:
            - name: JWT_SECRET
              valueFrom:
                secretKeyRef:
                  name: openapi-gateway-secret
                  key: jwt-secret
            - name: K8S_GATEWAY_TOKEN
              valueFrom:
                secretKeyRef:
                  name: openapi-gateway-secret
                  key: integration-gateway-token   # 受限角色令牌，绝非平台管理员令牌
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8081
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 600m
              memory: 512Mi

# file: deploy/gateway-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: openapi-gateway
  namespace: paas-system
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "30"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.paas.example.com
      secretName: openapi-gateway-tls
  rules:
    - host: api.paas.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: openapi-gateway
                port:
                  number: 8081
          - path: /oauth
            pathType: Prefix
            backend:
              service:
                name: openapi-gateway
                port:
                  number: 8081

# file: deploy/gateway-ratelimit.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: openapi-gateway-config
  namespace: paas-system
data:
  # 生产环境严格阈值；压测上限需远低于此，留足安全余量
  RATE_LIMIT_RPS: "50"           # 每客户端每秒请求数（生产 SLA）
  RATE_LIMIT_BURST: "100"
  CIRCUIT_BREAKER_THRESHOLD: "20"  # 连续错误数触发熔断
  CIRCUIT_BREAKER_TIMEOUT: "10s"
  # 测试环境覆盖（通过 env=test 的部署使用独立 ConfigMap）：
  # RATE_LIMIT_RPS: "500"
  # CIRCUIT_BREAKER_THRESHOLD: "200"

# file: deploy/webhook-receiver-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: webhook-receiver
  namespace: paas-system
  labels:
    app: openapi-gateway
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: webhook-receiver-role
  namespace: paas-system
rules:
  - apiGroups: [""]
    resources: ["events", "configmaps"]
    verbs: ["get", "list", "watch", "create", "update", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: webhook-receiver-binding
  namespace: paas-system
subjects:
  - kind: ServiceAccount
    name: webhook-receiver
    namespace: paas-system
roleRef:
  kind: Role
  name: webhook-receiver-role
  apiGroup: rbac.authorization.k8s.io

// file: internal/auth/jwt.go
package auth

import (
	"errors"
	"time"

	"github.com/golang-jwt/jwt/v5"
)

var (
	ErrTokenExpired = errors.New("token expired")
	ErrTokenInvalid = errors.New("token invalid")
)

// Claims 客户端令牌声明，含最小权限作用域与受限角色。
type Claims struct {
	ClientID string   `json:"cid"`
	Tenant   string   `json:"tid"`
	Env      string   `json:"env"`
	Scopes   []string `json:"scp"` // 如 quota:read
	Role     string   `json:"role"` // integration-restricted
	jwt.RegisteredClaims
}

// IssueToken 签发 OAuth2 客户端凭证换取的 JWT（客户端凭证模式）。
func IssueToken(secret, clientID, tenant, env string, scopes []string, ttl time.Duration) (string, error) {
	now := time.Now()
	claims := Claims{
		ClientID: clientID,
		Tenant:   tenant,
		Env:      env,
		Scopes:   scopes,
		Role:     "integration-restricted",
		RegisteredClaims: jwt.RegisteredClaims{
			Issuer:    "paas-openapi",
			Subject:   clientID,
			IssuedAt:  jwt.NewNumericDate(now),
			ExpiresAt: jwt.NewNumericDate(now.Add(ttl)),
		},
	}
	tok := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	return tok.SignedString([]byte(secret))
}

// ParseToken 校验 JWT 签名与有效期。
func ParseToken(secret, tokenStr string) (*Claims, error) {
	tok, err := jwt.ParseWithClaims(tokenStr, &Claims{}, func(t *jwt.Token) (interface{}, error) {
		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, ErrTokenInvalid
		}
		return []byte(secret), nil
	})
	if err != nil {
		if errors.Is(err, jwt.ErrTokenExpired) {
			return nil, ErrTokenExpired
		}
		return nil, ErrTokenInvalid
	}
	claims, ok := tok.Claims.(*Claims)
	if !ok || !tok.Valid {
		return nil, ErrTokenInvalid
	}
	return claims, nil
}

// HasScope 校验作用域是否满足。
func (c *Claims) HasScope(scope string) bool {
	for _, s := range c.Scopes {
		if s == scope {
			return true
		}
	}
	return false
}

// file: internal/auth/oauth2.go
package auth

import (
	"context"
	"net/http"
	"time"

	"github.com/gin-gonic/gin"
)

// ClientRecord OAuth2 客户端凭证记录（生产应使用加密存储 + 作用域白名单）。
type ClientRecord struct {
	ClientID string
	Scopes   []string
	Tenant   string
	Env      string
}

// ClientStore 客户端凭证存储接口。
type ClientStore interface {
	Verify(ctx context.Context, clientID, clientSecret string) (*ClientRecord, error)
}

// TokenHandler 实现 OAuth2 客户端凭证模式的 /oauth/token。
func TokenHandler(store ClientStore, secret string, ttl time.Duration) gin.HandlerFunc {
	return func(c *gin.Context) {
		clientID := c.PostForm("client_id")
		clientSecret := c.PostForm("client_secret")
		grantType := c.PostForm("grant_type")
		if grantType != "client_credentials" {
			c.JSON(http.StatusBadRequest, gin.H{"error": "unsupported_grant_type"})
			return
		}
		rec, err := store.Verify(c.Request.Context(), clientID, clientSecret)
		if err != nil {
			c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid_client"})
			return
		}
		tok, err := IssueToken(secret, rec.ClientID, rec.Tenant, rec.Env, rec.Scopes, ttl)
		if err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "server_error"})
			return
		}
		c.JSON(http.StatusOK, gin.H{
			"access_token": tok,
			"token_type":   "Bearer",
			"expires_in":   int(ttl.Seconds()),
			"scope":        rec.Scopes,
		})
	}
}

// file: internal/auth/signature.go
package auth

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strings"
)

// SignPayload 对载荷做 HMAC-SHA256 签名（Webhook 回调校验 / 请求签名）。
func SignPayload(secret string, body []byte) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	return hex.EncodeToString(mac.Sum(nil))
}

// VerifySignature 校验 X-Signature: t=<ts>,v=<hmac>，防重放需在调用方校验 ts 新鲜度。
func VerifySignature(secret, body, header string) bool {
	if header == "" {
		return false
	}
	var sig string
	for _, p := range strings.Split(header, ",") {
		if strings.HasPrefix(p, "v=") {
			sig = strings.TrimPrefix(p, "v=")
		}
	}
	if sig == "" {
		sig = header // 兼容纯签名格式
	}
	expected := SignPayload(secret, body)
	return hmac.Equal([]byte(expected), []byte(sig))
}

// file: internal/k8s/gateway.go
package k8s

import (
	"net/http"

	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
)

// RestrictedRoundTripper 注入"集成服务受限角色"令牌与目标集群标签，
// 开放 API 绝不下发平台管理员令牌，仅能执行白名单动作。
type RestrictedRoundTripper struct {
	GatewayToken string
	Cluster      string
	ClientID     string
	Next         http.RoundTripper
}

func (rt *RestrictedRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
	req.Header.Set("Authorization", "Bearer "+rt.GatewayToken)
	req.Header.Set("X-PaaS-Cluster", rt.Cluster)
	req.Header.Set("X-Client-Id", rt.ClientID) // 带 client_id 标签进联邦
	req.Header.Set("X-PaaS-Role", "integration-restricted")
	return rt.Next.RoundTrip(req)
}

// Dial 构造经统一 K8s API 网关的受限角色客户端。
func Dial(gatewayAddr, gatewayToken, cluster, clientID string) (*kubernetes.Clientset, error) {
	cfg := &rest.Config{Host: gatewayAddr}
	cfg.WrapTransport = func(rt http.RoundTripper) http.RoundTripper {
		return &RestrictedRoundTripper{
			GatewayToken: gatewayToken,
			Cluster:      cluster,
			ClientID:     clientID,
			Next:         rt,
		}
	}
	return kubernetes.NewForConfig(cfg)
}

// file: internal/webhook/dispatch.go
package webhook

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"

	"github.com/example/paas/openapi/internal/auth"
)

// Event 平台对外事件。
type Event struct {
	Type      string          `json:"type"` // app.published / alert.raised / approval.decided
	Tenant    string          `json:"tenant"`
	Env       string          `json:"env"`
	Cluster   string          `json:"cluster"`
	ClientID  string          `json:"client_id"`
	Timestamp time.Time       `json:"timestamp"`
	Payload   json.RawMessage `json:"payload"`
}

// Subscription Webhook 订阅。
type Subscription struct {
	ID          string `json:"id"`
	ClientID    string `json:"client_id"`
	EventType   string `json:"event_type"`
	CallbackURL string `json:"callback_url"`
	Secret      string `json:"secret"`
}

// Dispatcher 事件分发器：签名回调 + 失败重试 + 死信队列。
type Dispatcher struct {
	subs   map[string][]Subscription
	client *http.Client
	sign   func(secret string, body []byte) string
	dlq    chan Event // 死信队列，可被重放
}

func NewDispatcher() *Dispatcher {
	return &Dispatcher{
		subs:   map[string][]Subscription{},
		client: &http.Client{Timeout: 5 * time.Second},
		sign:   auth.SignPayload,
		dlq:    make(chan Event, 1000),
	}
}

// Subscribe 注册事件订阅。
func (d *Dispatcher) Subscribe(s Subscription) {
	d.subs[s.EventType] = append(d.subs[s.EventType], s)
}

// Dispatch 投递事件，至多重试 3 次，失败进死信队列（不阻塞主链路）。
func (d *Dispatcher) Dispatch(ctx context.Context, e Event) error {
	for _, s := range d.subs[e.Type] {
		body, _ := json.Marshal(e)
		sig := d.sign(s.Secret, body)
		req, err := http.NewRequestWithContext(ctx, http.MethodPost, s.CallbackURL, bytes.NewReader(body))
		if err != nil {
			d.toDLQ(e)
			continue
		}
		req.Header.Set("Content-Type", "application/json")
		req.Header.Set("X-PaaS-Signature", sig)
		req.Header.Set("X-PaaS-Event", e.Type)
		ok := false
		for attempt := 0; attempt < 3; attempt++ {
			resp, derr := d.client.Do(req)
			if derr == nil && resp != nil && resp.StatusCode < 300 {
				_ = resp.Body.Close()
				ok = true
				break
			}
			if resp != nil {
				_ = resp.Body.Close()
			}
			time.Sleep(time.Duration(attempt+1) * time.Second)
		}
		if !ok {
			d.toDLQ(e)
			fmt.Printf("webhook %s delivered to DLQ\n", s.ID)
		}
	}
	return nil
}

func (d *Dispatcher) toDLQ(e Event) {
	select {
	case d.dlq <- e:
	default:
		fmt.Println("DLQ full, drop event")
	}
}

// DeadLetter 返回死信队列可读通道，供运维重放。
func (d *Dispatcher) DeadLetter() <-chan Event { return d.dlq }

# 步骤 1：集成工程师在后台为第三方创建 OAuth2 客户端(env=测试)，作用域 quota:read
# 步骤 2：测试环境审批可自动通过，下发 client_id / secret
# 步骤 3：第三方用客户端凭证换 JWT，调用 GET /api/v1/tenants/{id}/quota
curl -X POST "https://api.paas.example.com/oauth/token" \
  -d "grant_type=client_credentials&client_id=isv-cmdb-001&client_secret=s3cr3t"
# -> {"access_token":"eyJ...","expires_in":7200,"scope":["quota:read"]}

# 步骤 4：在后台订阅"应用发布完成"Webhook，指向测试 ITSM 沙箱
curl -X POST "https://api.paas.example.com/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"id":"itsm-publish","client_id":"isv-cmdb-001","event_type":"app.published","callback_url":"https://itsm-sandbox.internal/hooks/paas","secret":"hook-secret"}'

# 步骤 5：联邦 Grafana API 大盘确认 client_id 维度调用量出现

# 步骤 1：集成工程师提交客户端申请，作用域最小化，env=生产
# 步骤 2：触发多级审批（安全 + 租户 owner），审批事件进审计
# 步骤 3：审批通过后下发凭据，限流阈值按生产 SLA 设定（如 50 QPS）
# 步骤 4：Webhook 回调地址需 HTTPS + 签名校验，指向生产 ITSM
curl -X POST "https://api.paas.example.com/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $PROD_TOKEN" \
  -d '{"id":"itsm-publish-prod","client_id":"isv-cmdb-001","event_type":"app.published","callback_url":"https://itsm.internal.example.com/hooks/paas","secret":"prod-hook-secret"}'
# 步骤 5：第三方调用，所有请求经鉴权+限流，审计员核验 90 天可查

// file: internal/middleware/auth.go
package middleware

import (
	"bytes"
	"io"
	"strings"

	"github.com/gin-gonic/gin"

	"github.com/example/paas/openapi/internal/auth"
	"github.com/example/paas/openapi/internal/metrics"
)

// Auth 鉴权中间件：优先校验 Bearer JWT（OAuth2），
// 也支持 HMAC 签名请求（X-Client-Id + X-Signature）。
func Auth(secret, requiredScope string) gin.HandlerFunc {
	return func(c *gin.Context) {
		authz := c.GetHeader("Authorization")
		if strings.HasPrefix(authz, "Bearer ") {
			token := strings.TrimPrefix(authz, "Bearer ")
			claims, err := auth.ParseToken(secret, token)
			if err != nil {
				metrics.AuthFailures.WithLabelValues("", pickEnv(c)).Inc()
				c.AbortWithStatusJSON(401, gin.H{"error": "invalid_token"})
				return
			}
			if requiredScope != "" && !claims.HasScope(requiredScope) {
				c.AbortWithStatusJSON(403, gin.H{"error": "insufficient_scope"})
				return
			}
			c.Set("claims", claims)
			c.Set("client_id", claims.ClientID)
			c.Set("tenant", claims.Tenant)
			c.Set("env", claims.Env)
			c.Next()
			return
		}

		// HMAC 签名鉴权
		clientID := c.GetHeader("X-Client-Id")
		sig := c.GetHeader("X-Signature")
		body, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.AbortWithStatusJSON(400, gin.H{"error": "bad_request"})
			return
		}
		c.Request.Body = io.NopCloser(bytes.NewReader(body)) // 还原，供后续 handler 读取
		if clientID == "" || !auth.VerifySignature(secret, body, sig) {
			metrics.AuthFailures.WithLabelValues(clientID, pickEnv(c)).Inc()
			c.AbortWithStatusJSON(401, gin.H{"error": "unauthenticated"})
			return
		}
		c.Set("client_id", clientID)
		c.Next()
	}
}

// RequireScope 在已鉴权后校验作用域（JWT 路径）。
func RequireScope(scope string) gin.HandlerFunc {
	return func(c *gin.Context) {
		cl, ok := c.Get("claims")
		if !ok {
			c.AbortWithStatusJSON(401, gin.H{"error": "unauthenticated"})
			return
		}
		claims, ok := cl.(*auth.Claims)
		if !ok || !claims.HasScope(scope) {
			c.AbortWithStatusJSON(403, gin.H{"error": "insufficient_scope"})
			return
		}
		c.Next()
	}
}

func pickEnv(c *gin.Context) string {
	if v, ok := c.Get("env"); ok {
		if s, ok := v.(string); ok && s != "" {
			return s
		}
	}
	return c.Query("env")
}

// file: internal/middleware/ratelimit.go
package middleware

import (
	"sync"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/sony/gobreaker"
	"golang.org/x/time/rate"

	"github.com/example/paas/openapi/internal/auth"
	"github.com/example/paas/openapi/internal/metrics"
)

type limiterSet struct {
	mu      sync.Mutex
	limiters map[string]*rate.Limiter
	rps     int
	burst   int
}

func (l *limiterSet) get(clientID string) *rate.Limiter {
	l.mu.Lock()
	defer l.mu.Unlock()
	lim, ok := l.limiters[clientID]
	if !ok {
		lim = rate.NewLimiter(rate.Limit(l.rps), l.burst)
		l.limiters[clientID] = lim
	}
	return lim
}

// RateLimit 按客户端维度限流；触发则返回 429 并计入指标（★禁止删减 限流）。
func RateLimit(rps, burst int) gin.HandlerFunc {
	ls := &limiterSet{limiters: map[string]*rate.Limiter{}, rps: rps, burst: burst}
	return func(c *gin.Context) {
		cid, _ := c.Get("client_id")
		clientID, _ := cid.(string)
		if clientID == "" {
			if cl, ok := c.Get("claims"); ok {
				if claims, ok := cl.(*auth.Claims); ok {
					clientID = claims.ClientID
				}
			}
		}
		if clientID == "" {
			clientID = c.ClientIP()
		}
		if !ls.get(clientID).Allow() {
			metrics.RateLimited.WithLabelValues(clientID, pickEnv(c)).Inc()
			c.AbortWithStatusJSON(429, gin.H{"error": "rate_limited", "retry_after": burst / rps})
			return
		}
		c.Next()
	}
}

// NewCircuitBreaker 构造后端调用熔断保护器（连续错误触发硬熔断，避免雪崩）。
func NewCircuitBreaker(threshold int, timeout time.Duration) *gobreaker.CircuitBreaker {
	return gobreaker.NewCircuitBreaker(gobreaker.Settings{
		Name:       "k8s-gateway",
		MaxRequests: uint32(threshold),
		Timeout:     timeout,
		OnStateChange: func(_ string, _ gobreaker.State, to gobreaker.State) {
			if to == gobreaker.StateOpen {
				metrics.CircuitOpen.Set(1)
			} else {
				metrics.CircuitOpen.Set(0)
			}
		},
	})
}

// file: internal/api/handler.go
package api

import (
	"context"
	"fmt"
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/sony/gobreaker"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

	"github.com/example/paas/openapi/internal/auth"
	"github.com/example/paas/openapi/internal/k8s"
	"github.com/example/paas/openapi/internal/metrics"
	"github.com/example/paas/openapi/internal/webhook"
)

// Server 开放 API 服务核心。
type Server struct {
	gatewayAddr  string
	gatewayToken string
	breaker      *gobreaker.CircuitBreaker
	dispatcher   *webhook.Dispatcher
}

func NewServer(gatewayAddr, gatewayToken string, breaker *gobreaker.CircuitBreaker, dispatcher *webhook.Dispatcher) *Server {
	return &Server{gatewayAddr: gatewayAddr, gatewayToken: gatewayToken, breaker: breaker, dispatcher: dispatcher}
}

func envToCluster(env string) string {
	switch env {
	case "prod":
		return "prod-cluster"
	case "staging":
		return "staging-cluster"
	case "test":
		return "test-cluster"
	default:
		return "dev-cluster"
	}
}

// GetQuota GET /api/v1/tenants/:id/quota  经受限角色经网关查询配额。
func (s *Server) GetQuota(c *gin.Context) {
	cl, _ := c.Get("claims")
	claims, _ := cl.(*auth.Claims)
	tenant := c.Param("id")
	env := c.Query("env")
	if env == "" && claims != nil {
		env = claims.Env
	}
	cluster := c.Query("cluster")
	if cluster == "" {
		cluster = envToCluster(env)
	}
	clientID := ""
	if claims != nil {
		clientID = claims.ClientID
	}

	cs, err := k8s.Dial(s.gatewayAddr, s.gatewayToken, cluster, clientID)
	if err != nil {
		metrics.Requests.WithLabelValues(clientID, tenant, env, cluster, "quota:read", "fail").Inc()
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	ns := fmt.Sprintf("%s-%s", tenant, env)
	rqName := fmt.Sprintf("quota-%s-%s", tenant, env)

	// 后端调用经熔断保护，避免统一网关抖动时雪崩
	res, err := s.breaker.Execute(func() (interface{}, error) {
		return cs.CoreV1().ResourceQuotas(ns).Get(c.Request.Context(), rqName, metav1.GetOptions{})
	})
	if err != nil {
		metrics.Requests.WithLabelValues(clientID, tenant, env, cluster, "quota:read", "fail").Inc()
		c.JSON(http.StatusBadGateway, gin.H{"error": "upstream_unavailable", "detail": err.Error()})
		return
	}
	rq := res.(*corev1.ResourceQuota)
	metrics.Requests.WithLabelValues(clientID, tenant, env, cluster, "quota:read", "success").Inc()
	c.JSON(http.StatusOK, gin.H{
		"tenant":  tenant,
		"env":     env,
		"cluster": cluster,
		"hard":    rq.Status.Hard,
		"used":    rq.Status.Used,
	})
}

// RegisterWebhook POST /api/v1/webhooks/subscriptions  订阅事件。
func (s *Server) RegisterWebhook(c *gin.Context) {
	var sub webhook.Subscription
	if err := c.ShouldBindJSON(&sub); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	s.dispatcher.Subscribe(sub)
	c.JSON(http.StatusCreated, gin.H{"id": sub.ID, "status": "subscribed"})
}

// PublishEvent 供平台内部在状态变化时调用，对外分发 Webhook。
func (s *Server) PublishEvent(ctx context.Context, e webhook.Event) error {
	return s.dispatcher.Dispatch(ctx, e)
}

// file: sdk/go/paas/client.go
package paas

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

// Client PaaS 开放 API Go SDK 调用示例。
type Client struct {
	BaseURL string
	Token   string
	HTTP    *http.Client
}

// NewClient 用 OAuth2 换取的 JWT 构造 SDK 客户端。
func NewClient(baseURL, token string) *Client {
	return &Client{BaseURL: baseURL, Token: token, HTTP: &http.Client{Timeout: 15 * time.Second}}
}

// Quota 配额查询结果。
type Quota struct {
	Tenant  string            `json:"tenant"`
	Env     string            `json:"env"`
	Cluster string            `json:"cluster"`
	Hard    map[string]string `json:"hard"`
	Used    map[string]string `json:"used"`
}

// GetQuota 调用 GET /api/v1/tenants/:id/quota（需 scope quota:read）。
func (c *Client) GetQuota(ctx context.Context, tenant, env, cluster string) (*Quota, error) {
	url := fmt.Sprintf("%s/api/v1/tenants/%s/quota?env=%s&cluster=%s", c.BaseURL, tenant, env, cluster)
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+c.Token)
	resp, err := c.HTTP.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("openapi status %d: %s", resp.StatusCode, string(body))
	}
	var q Quota
	if err := json.Unmarshal(body, &q); err != nil {
		return nil, err
	}
	return &q, nil
}

// Example 展示第三方如何用 SDK 查询租户配额。
func Example() {
	client := NewClient("https://api.paas.example.com", "eyJhbGciOi...")
	ctx := context.Background()
	q, err := client.GetQuota(ctx, "acme", "prod", "prod-cluster")
	if err != nil {
		panic(err)
	}
	fmt.Printf("acme/prod quota used cpu=%v\n", q.Used["cpu"])
}

// file: cmd/gateway/main.go
package main

import (
	"context"
	"errors"
	"log"
	"net/http"
	"os"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/prometheus/client_golang/prometheus/promhttp"
	"github.com/sony/gobreaker"

	"github.com/example/paas/openapi/internal/api"
	"github.com/example/paas/openapi/internal/auth"
	"github.com/example/paas/openapi/internal/middleware"
	"github.com/example/paas/openapi/internal/webhook"
)

// memoryClientStore 演示用内存客户端存储；生产应使用加密存储 + 作用域白名单。
type memoryClientStore struct {
	clients map[string]auth.ClientRecord
	secrets map[string]string
}

func (m *memoryClientStore) Verify(ctx context.Context, clientID, clientSecret string) (*auth.ClientRecord, error) {
	rec, ok := m.clients[clientID]
	if !ok || m.secrets[clientID] != clientSecret {
		return nil, errors.New("invalid client")
	}
	return &rec, nil
}

func main() {
	secret := os.Getenv("JWT_SECRET")
	if secret == "" {
		secret = "change-me-in-prod"
	}
	gatewayAddr := os.Getenv("K8S_GATEWAY_ADDR")
	gatewayToken := os.Getenv("K8S_GATEWAY_TOKEN")

	store := &memoryClientStore{
		clients: map[string]auth.ClientRecord{
			"isv-cmdb-001": {ClientID: "isv-cmdb-001", Tenant: "acme", Env: "prod", Scopes: []string{"quota:read"}},
		},
		secrets: map[string]string{"isv-cmdb-001": "s3cr3t"},
	}

	breaker := middleware.NewCircuitBreaker(20, 10*time.Second)
	dispatcher := webhook.NewDispatcher()
	dispatcher.Subscribe(webhook.Subscription{
		ID: "itsm-publish", ClientID: "isv-cmdb-001", EventType: "app.published",
		CallbackURL: "https://itsm.internal.example.com/hooks/paas", Secret: "hook-secret",
	})

	srv := api.NewServer(gatewayAddr, gatewayToken, breaker, dispatcher)
	rps, burst := 50, 100 // 生产严格阈值；测试环境覆盖为 500/1000

	r := gin.New()
	r.Use(gin.Recovery())
	r.POST("/oauth/token", auth.TokenHandler(store, secret, 2*time.Hour))
	apiV1 := r.Group("/api/v1")
	apiV1.Use(middleware.Auth(secret, ""), middleware.RateLimit(rps, burst))
	{
		apiV1.GET("/tenants/:id/quota", middleware.RequireScope("quota:read"), srv.GetQuota)
		apiV1.POST("/webhooks/subscriptions", srv.RegisterWebhook)
	}
	r.GET("/metrics", gin.WrapH(promhttp.Handler()))
	r.GET("/healthz", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"status": "ok"}) })

	addr := os.Getenv("LISTEN_ADDR")
	if addr == "" {
		addr = ":8081"
	}
	log.Printf("openapi-gateway listening on %s", addr)
	if err := r.Run(addr); err != nil {
		log.Fatal(err)
	}
}

# ── 生成 API Token（OAuth2 客户端凭证）────────────────────
TOKEN=$(curl -s -X POST "https://api.paas.example.com/oauth/token" \
  -d "grant_type=client_credentials&client_id=isv-cmdb-001&client_secret=s3cr3t" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
echo "token=${TOKEN:0:12}..."

# ── 调用开放 API（查询租户配额）──────────────────────────
curl "https://api.paas.example.com/api/v1/tenants/acme/quota?env=prod&cluster=prod-cluster" \
  -H "Authorization: Bearer $TOKEN"

# 若用 HMAC 签名方式（无 JWT）：
BODY='{"tenant":"acme"}'
SIG=$(python3 -c "import hmac,hashlib,sys;print(hmac.new(b'hook-secret', sys.stdin.read().encode(), hashlib.sha256).hexdigest())" <<< "$BODY")
curl -X POST "https://api.paas.example.com/api/v1/tenants/acme/quota" \
  -H "X-Client-Id: isv-cmdb-001" -H "X-Signature: v=$SIG" -d "$BODY"

# ── 注册 Webhook（订阅应用发布完成事件到 ITSM）────────────
curl -X POST "https://api.paas.example.com/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"id":"itsm-publish","client_id":"isv-cmdb-001","event_type":"app.published","callback_url":"https://itsm.internal.example.com/hooks/paas","secret":"prod-hook-secret"}'

# ── 触发限流并观察熔断（压测 200 QPS，生产阈值 50）────────
hey -z 30s -q 200 -H "Authorization: Bearer $TOKEN" \
  "https://api.paas.example.com/api/v1/tenants/acme/quota?env=prod&cluster=prod-cluster"
# 在联邦 Grafana API 大盘确认 paas_openapi_rate_limited_total 与 paas_openapi_circuit_open

# ── 重放死信队列中的失败 Webhook 事件 ────────────────────
# 通过管理端口 /debug/dlq 拉取并重投（生产由运维工具执行）

# file: deploy/gateway-prometheus.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: openapi-gateway
  namespace: paas-system
  labels:
    release: kube-prometheus-stack
spec:
  selector:
    matchLabels:
      app: openapi-gateway
  endpoints:
    - port: metrics
      interval: 10s
---
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: openapi-gateway-rules
  namespace: paas-system
  labels:
    release: kube-prometheus-stack
spec:
  groups:
    - name: openapi-gateway
      rules:
        - alert: OpenAPIRateLimitedSpike
          expr: |
            sum(rate(paas_openapi_rate_limited_total[5m])) by (client_id,env)
            >
            sum(rate(paas_openapi_requests_total[5m])) by (client_id,env) * 0.3            
          for: 5m
          labels:
            severity: warning
            env: "{{ $labels.env }}"
          annotations:
            summary: "开放API限流拒绝占比超30% client_id={{ $labels.client_id }}"
        - alert: OpenAPIAuthFailSpike
          expr: |
            sum(rate(paas_openapi_auth_failures_total[5m])) by (client_id,env) > 10            
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "鉴权失败激增 client_id={{ $labels.client_id }}"
        - alert: OpenAPICircuitOpen
          expr: paas_openapi_circuit_open == 1
          for: 1m
          labels:
            severity: critical
          annotations:
            summary: "开放API后端熔断已打开，避免雪崩"

// file: internal/metrics/metrics.go
package metrics

import (
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promauto"
)

var (
	Requests = promauto.NewCounterVec(prometheus.CounterOpts{
		Name: "paas_openapi_requests_total",
		Help: "开放API调用量",
	}, []string{"client_id", "tenant", "env", "cluster", "action", "result"})

	RateLimited = promauto.NewCounterVec(prometheus.CounterOpts{
		Name: "paas_openapi_rate_limited_total",
		Help: "开放API被限流次数",
	}, []string{"client_id", "env"})

	AuthFailures = promauto.NewCounterVec(prometheus.CounterOpts{
		Name: "paas_openapi_auth_failures_total",
		Help: "开放API鉴权失败次数",
	}, []string{"client_id", "env"})

	CircuitOpen = promauto.NewGauge(prometheus.GaugeOpts{
		Name: "paas_openapi_circuit_open",
		Help: "后端熔断是否打开(1=打开)",
	})
)