LLM Gateway 架构：控制面、数据面与生产边界

{
  "request_id": "req_01",
  "tenant_id": "tenant_red",
  "config_version": "2026-08-09.3",
  "virtual_model": "support-chat",
  "backend_id": "provider_a_chat",
  "attempt": 1,
  "status": "completed",
  "input_units": 1840,
  "output_units": 276,
  "usage_source": "provider_response",
  "price_catalog_version": "catalog_42",
  "estimated_cost": "0.000000",
  "currency": "USD"
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"os"
	"sort"
	"strings"
)

type Policy struct {
	ConfigVersion string     `json:"config_version"`
	Backends      []Backend  `json:"backends"`
	Routes        []Route    `json:"routes"`
	Tenants       []Tenant   `json:"tenants"`
	Telemetry     *Telemetry `json:"telemetry"`
}

type Backend struct {
	ID           string   `json:"id"`
	Capabilities []string `json:"capabilities"`
	SecretRef    string   `json:"secret_ref"`
}

type Route struct {
	Alias                string       `json:"alias"`
	RequiredCapabilities []string     `json:"required_capabilities"`
	Candidates           []string     `json:"candidates"`
	Retry                *RetryPolicy `json:"retry"`
}

type RetryPolicy struct {
	MaxAttempts            *int     `json:"max_attempts"`
	AfterDownstreamStarted *bool    `json:"after_downstream_started"`
	BudgetRatio            *float64 `json:"budget_ratio"`
}

type Tenant struct {
	ID                string `json:"id"`
	CacheNamespace    string `json:"cache_namespace"`
	OnBudgetExhausted string `json:"on_budget_exhausted"`
}

type Telemetry struct {
	LogPromptBody *bool `json:"log_prompt_body"`
}

const examplePolicy = `{
  "config_version": "2026-10-05.1",
  "backends": [{
    "id": "provider-a",
    "capabilities": ["text", "json_schema"],
    "secret_ref": "secret://provider-a"
  }],
  "routes": [{
    "alias": "support-chat",
    "required_capabilities": ["text", "json_schema"],
    "candidates": ["provider-a"],
    "retry": {
      "max_attempts": 2,
      "after_downstream_started": false,
      "budget_ratio": 0.1
    }
  }],
  "tenants": [{
    "id": "tenant-a",
    "cache_namespace": "tenant-a",
    "on_budget_exhausted": "reject"
  }],
  "telemetry": {"log_prompt_body": false}
}`

func require(condition bool, message string, errors *[]string) {
	if !condition {
		*errors = append(*errors, message)
	}
}

func stringSet(values []string, field string, errors *[]string) map[string]bool {
	result := make(map[string]bool, len(values))
	if values == nil {
		*errors = append(*errors, field+" must be a list")
		return result
	}
	for _, value := range values {
		if strings.TrimSpace(value) == "" {
			*errors = append(*errors, field+" contains an empty string")
			continue
		}
		result[value] = true
	}
	return result
}

func validate(policy Policy) []string {
	var errors []string
	require(strings.TrimSpace(policy.ConfigVersion) != "", "config_version is required", &errors)
	require(policy.Backends != nil, "backends must be a list", &errors)
	require(policy.Routes != nil, "routes must be a list", &errors)
	require(policy.Tenants != nil, "tenants must be a list", &errors)

	backends := make(map[string]map[string]bool, len(policy.Backends))
	for index, backend := range policy.Backends {
		if strings.TrimSpace(backend.ID) == "" {
			errors = append(errors, fmt.Sprintf("backends[%d].id is required", index))
			continue
		}
		if _, exists := backends[backend.ID]; exists {
			errors = append(errors, "duplicate backend id: "+backend.ID)
			continue
		}
		backends[backend.ID] = stringSet(
			backend.Capabilities,
			"backend "+backend.ID+" capabilities",
			&errors,
		)
		require(
			strings.TrimSpace(backend.SecretRef) != "",
			"backend "+backend.ID+" must use secret_ref",
			&errors,
		)
	}

	aliases := make(map[string]bool, len(policy.Routes))
	for index, route := range policy.Routes {
		if strings.TrimSpace(route.Alias) == "" {
			errors = append(errors, fmt.Sprintf("routes[%d].alias is required", index))
			continue
		}
		require(!aliases[route.Alias], "duplicate route alias: "+route.Alias, &errors)
		aliases[route.Alias] = true
		required := stringSet(
			route.RequiredCapabilities,
			"route "+route.Alias+" required_capabilities",
			&errors,
		)
		candidates := stringSet(
			route.Candidates,
			"route "+route.Alias+" candidates",
			&errors,
		)
		require(len(candidates) > 0, "route "+route.Alias+" has no candidates", &errors)
		for backendID := range candidates {
			capabilities, exists := backends[backendID]
			require(exists, "route "+route.Alias+" references unknown backend "+backendID, &errors)
			if !exists {
				continue
			}
			var missing []string
			for capability := range required {
				if !capabilities[capability] {
					missing = append(missing, capability)
				}
			}
			sort.Strings(missing)
			require(
				len(missing) == 0,
				fmt.Sprintf("route %s backend %s lacks %v", route.Alias, backendID, missing),
				&errors,
			)
		}
		if route.Retry == nil {
			errors = append(errors, "route "+route.Alias+" retry is required")
			continue
		}
		retry := route.Retry
		require(
			retry.MaxAttempts != nil && *retry.MaxAttempts >= 1 && *retry.MaxAttempts <= 3,
			"route "+route.Alias+" max_attempts must be between 1 and 3",
			&errors,
		)
		require(
			retry.AfterDownstreamStarted != nil && !*retry.AfterDownstreamStarted,
			"route "+route.Alias+" must not retry after streaming starts",
			&errors,
		)
		require(
			retry.BudgetRatio != nil && *retry.BudgetRatio >= 0 && *retry.BudgetRatio <= 1,
			"route "+route.Alias+" budget_ratio must be in [0, 1]",
			&errors,
		)
	}

	for index, tenant := range policy.Tenants {
		require(
			strings.TrimSpace(tenant.ID) != "",
			fmt.Sprintf("tenants[%d].id is required", index),
			&errors,
		)
		require(
			strings.TrimSpace(tenant.CacheNamespace) != "",
			fmt.Sprintf("tenant %q needs an isolated cache_namespace", tenant.ID),
			&errors,
		)
		require(
			tenant.OnBudgetExhausted == "reject" ||
				tenant.OnBudgetExhausted == "manual_approval",
			fmt.Sprintf("tenant %q must reject or require approval when budget is exhausted", tenant.ID),
			&errors,
		)
	}

	require(policy.Telemetry != nil, "telemetry is required", &errors)
	if policy.Telemetry != nil {
		require(
			policy.Telemetry.LogPromptBody != nil && !*policy.Telemetry.LogPromptBody,
			"telemetry.log_prompt_body must explicitly be false",
			&errors,
		)
	}
	return errors
}

func decodePolicy(data []byte) (Policy, error) {
	var policy Policy
	decoder := json.NewDecoder(bytes.NewReader(data))
	decoder.DisallowUnknownFields()
	if err := decoder.Decode(&policy); err != nil {
		return Policy{}, err
	}
	if err := decoder.Decode(&struct{}{}); err != io.EOF {
		return Policy{}, fmt.Errorf("policy must contain one JSON object")
	}
	return policy, nil
}

func main() {
	data := []byte(examplePolicy)
	source := "embedded example"
	if len(os.Args) > 2 {
		fmt.Fprintln(os.Stderr, "usage: go run gateway_policy_validator.go [gateway-policy.json]")
		os.Exit(2)
	}
	if len(os.Args) == 2 {
		var err error
		source = os.Args[1]
		data, err = os.ReadFile(source)
		if err != nil {
			fmt.Fprintln(os.Stderr, err)
			os.Exit(2)
		}
	}

	policy, err := decodePolicy(data)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}
	if errors := validate(policy); len(errors) > 0 {
		for _, message := range errors {
			fmt.Fprintln(os.Stderr, "ERROR:", message)
		}
		os.Exit(1)
	}
	fmt.Println("valid policy:", source)
}