bootstrap

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 22, 2026 License: MIT Imports: 69 Imported by: 0

Documentation

Overview

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file registers app-service-specific runtime bindings during bootstrap. Keeps app-service mode assembly compact while preserving singleton startup behavior.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件在 bootstrap 阶段注册 app-service 模式专用的运行时绑定。 在保持单例启动语义的同时，让 app-service 模式装配保持精简。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file defines governance capability keys and provider backend keys as typed constants, replacing scattered hardcoded strings with a single source of truth.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件将治理能力名称和 Provider 后端名称定义为类型化常量， 用单一真实来源替代散布在代码中的硬编码字符串。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file maintains provider factory registries for bootstrap selection logic. Allows built-in and contributed capability providers to be resolved from config.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件维护 bootstrap 选择逻辑所依赖的 provider factory 注册表。 让内建和扩展能力 provider 可以通过配置值解析出来。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file selects capability providers from runtime configuration during bootstrap. Keeps config-driven microservice assembly centralized and predictable.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件在 bootstrap 阶段根据运行时配置选择能力 provider。 将配置驱动的微服务装配逻辑集中管理并保持可预测性。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file defines critical config schemas and fail-fast validation at startup. Uses go-playground/validator to catch missing or invalid config values early, instead of letting them silently become viper zero values that cause confusing runtime errors.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件定义关键配置的结构体 schema 与启动时 fail-fast 校验。 使用 go-playground/validator 在启动阶段就捕获缺失或无效的配置值， 避免它们被 viper 静默转为零值后引发难以排查的运行时错误。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file exposes /debug/cron HTTP endpoint for inspecting registered cron jobs.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件暴露 /debug/cron HTTP 端点，用于查看已注册的 cron 任务状态。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file builds the default bootstrap application for CLI and general startup paths. Reuses one shared provider assembly strategy for non-HTTP bootstrap entrypoints.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件为 CLI 和通用启动路径构建框架默认 bootstrap application。 为非 HTTP 的 bootstrap 入口复用统一的 provider 装配策略。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file centralizes mode-aware default provider backends for governance bootstrap. Provides stable source of truth for monolith, microservice, and gin-first defaults.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件集中维护治理 bootstrap 路径里按模式生效的默认 provider backend。 为 monolith、microservice、gin-first 三种模式提供统一默认值真源。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file builds the governance defaults table for the view=defaults inspect endpoint. Projects mode-aware feature defaults, provider defaults, and HTTP/RPC option defaults into one serializable, inspection-friendly snapshot.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件为 view=defaults 诊断视图构建治理默认值表。 将按模式生效的 feature 默认值、provider 默认值、HTTP/RPC 选项默认值 投影成一份可序列化、可检查的快照。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file exposes formal inspect/doctor HTTP view for governance results. Reuses the same governance summary used by startup logs and tests.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件为最终治理生效结果暴露统一的 inspect/doctor HTTP 视图。 复用启动日志和测试已经使用的同一份治理摘要。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file centralizes governance-mode detection for bootstrap and startup helpers. Keeps monolith and microservice default-provider behavior explicit in one place.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件集中处理 bootstrap 选择与启动 helper 使用的治理模式判断。 将 monolith 与 microservice 的默认 provider 语义显式收口到一个位置。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file overlays governance disable/provider overrides on shared config contract. Unifies config-driven and code-driven governance overrides in one effective view.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件在共享配置契约之上叠加治理关闭项和 provider 覆盖项。 将配置驱动与代码驱动的治理覆盖统一到同一个生效视图上。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file parses explicit governance overrides from config without repeating defaults. Supports “disable capability” and “replace provider backend” control paths.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件解析显式治理覆盖配置，而不要求调用方展开所有默认值。 支持低成本关闭某个治理能力和替换某个 provider backend 控制路径。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file builds governance summary for startup logs, tests, and inspect tooling. Makes “what is enabled/disabled” and “provider backends” observable in one place.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件生成统一的治理生效摘要，供启动日志、测试和后续 inspect 工具复用。 将启用了什么、关闭了什么、当前 provider backend 集中展示。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file assembles and runs the gRPC service alongside the HTTP mainline. Builds a reusable runtime carrying container, gRPC server, config, and logger.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件装配并运行与 HTTP 主线并行的 gRPC 服务。 构建复用型 runtime 对象，统一承载 container、gRPC server、config、logger 能力。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file assembles and runs the default HTTP service mainline. Builds reusable runtime carrying app, container, router, config, DB, Redis, JWT.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件装配并运行框架默认 HTTP 服务主线。 构建复用型 runtime 对象，统一承载 app、container、router、config、DB、Redis、JWT 能力。

Package bootstrap_test provides integration and boundary tests for HTTP service runtime bootstrapping.

适用场景： - 验证 HTTP Service runtime 的初始化、governance override 和 provider 注册行为。 - 验证 pprof / governance inspect 端点的路由注册与响应格式。 - 验证 governance summary 与 diagnostic 的构建与格式化逻辑。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file groups providers into stable bootstrap bundles by responsibility. Provides predictable provider slices for foundation, ORM, auth, business helpers.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件按职责把 provider 组织成稳定的 bootstrap 分组。 为应用装配代码提供 foundation、ORM、auth 和业务简化能力的可预测 provider 切片。

Package bootstrap provides framework bootstrap and assembly helpers for gorp. This file provides safe default provider bundle for monolith-friendly deployments. Prefers noop/local implementations for optional capabilities in single-process apps.

Bootstrap 包提供 gorp 框架的启动装配辅助能力。 本文件为单体友好部署提供安全的默认 provider 组合。 对单进程应用中可选的能力优先使用 noop/local 实现。

Index

Constants

View Source 
const (
	FeatureRequestIdentity = "request_identity"
	FeatureLogging         = "logging"
	FeatureRecovery        = "recovery"
	FeatureTimeout         = "timeout"
	FeatureMetrics         = "metrics"
	FeatureMetadata        = "metadata"
	FeatureTracing         = "tracing"
	FeatureSelector        = "selector"
	FeatureServiceAuth     = "serviceauth"
	FeatureCircuitBreaker  = "circuitbreaker"
	FeatureRetry           = "retry"
	FeatureLoadShedding    = "loadshedding"
	FeatureDiscovery       = "discovery"
)

────────────────────────────────────────────────────── Feature keys (used in governance.enable / governance.disable) 特性名称常量（用于 governance.enable / governance.disable） ──────────────────────────────────────────────────────

Variables

This section is empty.

Functions

func AuthProviders 

func AuthProviders() []runtimecontract.ServiceProvider

AuthProviders returns the providers used for business-side authentication.

AuthProviders 返回业务侧认证使用的 provider 集合。

func AutoMigrateModels 

func AutoMigrateModels(rt *HTTPServiceRuntime, models ...any) error

AutoMigrateModels runs Gorm auto-migration when DB runtime is available.

AutoMigrateModels 在 DB runtime 可用时执行 Gorm 自动迁移。

func BootGRPCService 

func BootGRPCService(serviceName string, opts GRPCServiceOptions, setup func(*GRPCServiceRuntime) error) error

BootGRPCService assembles, configures, and runs the standalone gRPC service. This is the gRPC counterpart of BootHTTPService, used when gRPC runs independently.

BootGRPCService 装配、配置并运行独立的 gRPC 服务。 这是 BootHTTPService 的 gRPC 对称入口，在 gRPC 独立运行时使用。

func BootHTTPService 

func BootHTTPService(opts HTTPServiceOptions, migrate func(*HTTPServiceRuntime) error, setup func(*HTTPServiceRuntime) error) (retErr error)

BootHTTPService assembles, configures, and runs the default HTTP service. Service name is read from config (app.name) automatically.

BootHTTPService 装配、配置并运行默认 HTTP 服务。 服务名自动从配置 app.name 读取。

func BuildGovernanceDefaultsTable 

func BuildGovernanceDefaultsTable(mode resiliencecontract.GovernanceMode) *resiliencecontract.GovernanceDefaultsTable

BuildGovernanceDefaultsTable builds the full governance defaults table for one mode. This is a pure function that only reads static defaults — no runtime config involved.

BuildGovernanceDefaultsTable 构建某个治理模式下完整的默认值表。 这是一个纯函数，只读取静态默认值，不涉及运行时配置。

func BusinessSimplificationProviders 

func BusinessSimplificationProviders() []runtimecontract.ServiceProvider

BusinessSimplificationProviders returns providers that simplify common business access patterns.

BusinessSimplificationProviders 返回用于简化常见业务接入的 provider 集合。

func CoreProviders 

func CoreProviders() []runtimecontract.ServiceProvider

CoreProviders is an alias for FoundationProviders.

CoreProviders 是 FoundationProviders 的同义入口。

func DefaultBootstrapHelpers 

func DefaultBootstrapHelpers() []string

DefaultBootstrapHelpers returns the helper names commonly surfaced to users.

DefaultBootstrapHelpers 返回通常对外暴露的 bootstrap helper 名称列表。

func DefaultCapabilityProviders 

func DefaultCapabilityProviders() []runtimecontract.ServiceProvider

DefaultCapabilityProviders returns the default non-foundation capability providers. Includes health checker for aggregated health status reporting.

DefaultCapabilityProviders 返回默认的非基础能力 provider 集合。 包含健康检查器用于聚合健康状态报告。

func DefaultProviders 

func DefaultProviders() []runtimecontract.ServiceProvider

DefaultProviders returns the default provider set used by bootstrap helpers.

DefaultProviders 返回 bootstrap helper 使用的默认 provider 集合。

func DetectGovernanceMode 

func DetectGovernanceMode(cfg datacontract.Config) resiliencecontract.GovernanceMode

DetectGovernanceMode resolves the runtime governance mode from config.

DetectGovernanceMode 从配置中解析运行时治理模式。

func FormatGovernanceDiagnostic 

func FormatGovernanceDiagnostic(summary GovernanceSummary) string

FormatGovernanceDiagnostic renders one human-readable governance diagnostic report.

FormatGovernanceDiagnostic 将治理结果渲染成人类可读的诊断文本。

func FormatGovernanceDiagnosticView 

func FormatGovernanceDiagnosticView(summary GovernanceSummary, view string) string

FormatGovernanceDiagnosticView renders one selected human-readable governance diagnostic view.

FormatGovernanceDiagnosticView 渲染指定视角的人类可读治理诊断文本。

func FormatGovernanceSummary 

func FormatGovernanceSummary(summary GovernanceSummary) string

FormatGovernanceSummary renders the governance summary into one stable log-friendly line.

FormatGovernanceSummary 将治理摘要渲染成稳定的日志字符串。

func FoundationProviders 

func FoundationProviders() []runtimecontract.ServiceProvider

FoundationProviders returns the baseline providers required by most applications.

FoundationProviders 返回大多数应用都需要的基础 provider 集合。

func IsGinHTTPMode 

func IsGinHTTPMode(httpMode resiliencecontract.HTTPMode) bool

IsGinHTTPMode reports whether the HTTP mode uses native gin.Context.

IsGinHTTPMode 返回 HTTP 模式是否使用原生 gin.Context。

func IsMicroMode 

func IsMicroMode(mode resiliencecontract.GovernanceMode) bool

IsMicroMode reports whether the given mode represents the microservice mainline.

IsMicroMode 返回当前模式是否代表微服务主线。

func MonolithFriendlyProviders 

func MonolithFriendlyProviders() []runtimecontract.ServiceProvider

MonolithFriendlyProviders returns the provider bundle tailored for monolith deployments.

MonolithFriendlyProviders 返回面向单体部署的 provider 组合。

func NewCLIApplication 

func NewCLIApplication() (*framework.Application, runtimecontract.Container, error)

NewCLIApplication builds a default application with CLI-oriented providers.

NewCLIApplication 构建带有 CLI 场景 provider 的默认 application。

func NewDefaultApplication 

func NewDefaultApplication() (*framework.Application, runtimecontract.Container, error)

NewDefaultApplication builds the default application used by general bootstrap flows.

NewDefaultApplication 构建通用 bootstrap 流程使用的默认 application。

func NormalizeGovernanceMode 

func NormalizeGovernanceMode(mode resiliencecontract.GovernanceMode) resiliencecontract.GovernanceMode

NormalizeGovernanceMode returns a supported governance mode, defaulting to mono.

NormalizeGovernanceMode 返回受支持的治理模式；未命中时默认回退为 mono。

func NormalizeHTTPMode 

func NormalizeHTTPMode(mode resiliencecontract.HTTPMode) resiliencecontract.HTTPMode

NormalizeHTTPMode returns a supported HTTP mode, defaulting to contract.

NormalizeHTTPMode 返回受支持的 HTTP 模式；未命中时默认回退为 contract。

func ORMRuntimeProviders 

func ORMRuntimeProviders() []runtimecontract.ServiceProvider

ORMRuntimeProviders returns the providers that expose ORM and DB runtime capabilities.

ORMRuntimeProviders 返回暴露 ORM 与数据库运行时能力的 provider 集合。

func RegisterAppServices 

func RegisterAppServices(c runtimecontract.Container, bindings map[string]runtimecontract.Factory)

RegisterAppServices registers app-service runtime bindings as singletons.

RegisterAppServices 以单例形式注册 app-service 运行时绑定。

func RegisterCircuitBreakerProviderFactory 

func RegisterCircuitBreakerProviderFactory(key string, factory providerFactory)

RegisterCircuitBreakerProviderFactory registers a circuit-breaker provider factory.

RegisterCircuitBreakerProviderFactory 注册熔断器 provider factory。

func RegisterConfigSourceProviderFactory 

func RegisterConfigSourceProviderFactory(key string, factory providerFactory)

RegisterConfigSourceProviderFactory registers a config-source provider factory.

RegisterConfigSourceProviderFactory 注册配置源 provider factory。

func RegisterCronInspectEndpoints 

func RegisterCronInspectEndpoints(router transportcontract.Router, cronSvc runtimecontract.Cron)

RegisterCronInspectEndpoints registers the /debug/cron and /doctor/cron endpoints. Displays all registered cron jobs with their schedule, last/next run time, and status.

RegisterCronInspectEndpoints 注册 /debug/cron 和 /doctor/cron 端点。 展示所有已注册 cron 任务的调度表达式、上次/下次执行时间及执行状态。

func RegisterDTMProviderFactory 

func RegisterDTMProviderFactory(key string, factory providerFactory)

RegisterDTMProviderFactory registers a DTM provider factory.

RegisterDTMProviderFactory 注册 DTM provider factory。

func RegisterDiscoveryProviderFactory 

func RegisterDiscoveryProviderFactory(key string, factory providerFactory)

RegisterDiscoveryProviderFactory registers a discovery provider factory.

RegisterDiscoveryProviderFactory 注册服务发现 provider factory。

func RegisterDistributedLockProviderFactory 

func RegisterDistributedLockProviderFactory(key string, factory providerFactory)

RegisterDistributedLockProviderFactory registers a distributed-lock provider factory.

RegisterDistributedLockProviderFactory 注册分布式锁 provider factory。

func RegisterGovernanceInspectEndpoints 

func RegisterGovernanceInspectEndpoints(router transportcontract.Router, summary GovernanceSummary)

RegisterGovernanceInspectEndpoints registers the formal governance inspect/doctor endpoints.

RegisterGovernanceInspectEndpoints 注册正式治理 inspect / doctor 端点。

func RegisterHealthCheck 

func RegisterHealthCheck(router transportcontract.Router, serviceName string)

RegisterHealthCheck registers the default health endpoint. If HealthChecker is bound in container, uses aggregated health check. Otherwise, falls back to simple health check.

RegisterHealthCheck 注册默认健康检查端点。 如果容器中绑定了 HealthChecker，使用聚合健康检查。 否则回退到简单健康检查。

func RegisterHealthCheckWithChecker 

func RegisterHealthCheckWithChecker(router transportcontract.Router, container runtimecontract.Container)

RegisterHealthCheckWithChecker registers health endpoints with HealthChecker. Uses aggregated health check with dependency status.

RegisterHealthCheckWithChecker 使用 HealthChecker 注册健康检查端点。 使用聚合健康检查，包含依赖状态。

func RegisterLoadShedderProviderFactory 

func RegisterLoadShedderProviderFactory(key string, factory providerFactory)

RegisterLoadShedderProviderFactory registers a load-shedder provider factory.

RegisterLoadShedderProviderFactory 注册过载保护 provider factory。

func RegisterMessageQueueProviderFactory 

func RegisterMessageQueueProviderFactory(key string, factory providerFactory)

RegisterMessageQueueProviderFactory registers a message-queue provider factory.

RegisterMessageQueueProviderFactory 注册消息队列 provider factory。

func RegisterMetadataProviderFactory 

func RegisterMetadataProviderFactory(key string, factory providerFactory)

RegisterMetadataProviderFactory registers a metadata provider factory.

RegisterMetadataProviderFactory 注册 metadata provider factory。

func RegisterMetricsEndpoint 

func RegisterMetricsEndpoint(router transportcontract.Router)

RegisterMetricsEndpoint registers the default metrics endpoint.

RegisterMetricsEndpoint 注册默认 metrics 端点。

func RegisterPprofEndpoints 

func RegisterPprofEndpoints(router transportcontract.Router)

RegisterPprofEndpoints registers the standard pprof endpoints.

RegisterPprofEndpoints 注册标准 pprof 端点。

func RegisterRPCProviderFactory 

func RegisterRPCProviderFactory(key string, factory providerFactory)

RegisterRPCProviderFactory registers an RPC provider factory.

RegisterRPCProviderFactory 注册 RPC provider factory。

func RegisterRetryProviderFactory 

func RegisterRetryProviderFactory(key string, factory providerFactory)

RegisterRetryProviderFactory registers a retry provider factory.

RegisterRetryProviderFactory 注册重试 provider factory。

func RegisterSelectedMicroserviceProviders 

func RegisterSelectedMicroserviceProviders(c runtimecontract.Container) error

RegisterSelectedMicroserviceProviders resolves and registers microservice capability providers into the container.

RegisterSelectedMicroserviceProviders 解析并将微服务能力 provider 注册到容器。

func RegisterSelectedMicroserviceProvidersWithMode 

func RegisterSelectedMicroserviceProvidersWithMode(c runtimecontract.Container, modeOverride string) error

RegisterSelectedMicroserviceProvidersWithMode resolves and registers microservice providers with an explicit mode override.

RegisterSelectedMicroserviceProvidersWithMode 在显式 mode 覆盖下解析并注册微服务 provider。

func RegisterSelectorProviderFactory 

func RegisterSelectorProviderFactory(key string, factory providerFactory)

RegisterSelectorProviderFactory registers a selector provider factory.

RegisterSelectorProviderFactory 注册选择器 provider factory。

func RegisterServiceAuthProviderFactory 

func RegisterServiceAuthProviderFactory(key string, factory providerFactory)

RegisterServiceAuthProviderFactory registers a service-auth provider factory.

RegisterServiceAuthProviderFactory 注册服务鉴权 provider factory。

func RegisterTracingProviderFactory 

func RegisterTracingProviderFactory(key string, factory providerFactory)

RegisterTracingProviderFactory registers a tracing provider factory.

RegisterTracingProviderFactory 注册 tracing provider factory。

func RegisterWebSocketProviderFactory 

func RegisterWebSocketProviderFactory(key string, factory providerFactory)

RegisterWebSocketProviderFactory registers a WebSocket provider factory.

RegisterWebSocketProviderFactory 注册 WebSocket provider factory。

func RunGRPC 

func RunGRPC(c runtimecontract.Container, logger observabilitycontract.Logger) error

RunGRPC runs the gRPC service through the host capability when present. Falls back to direct gRPC run mode when host is unavailable.

RunGRPC 优先通过 host 能力运行 gRPC 服务。 当 host 能力不可用时，回退到 gRPC 直跑模式。

func RunHTTP 

func RunHTTP(c runtimecontract.Container, logger observabilitycontract.Logger) error

RunHTTP runs the HTTP service through the host capability when present. In microservice mode, also starts the gRPC server alongside HTTP when the container has a GRPCServerRegistrar bound.

RunHTTP 优先通过 host 能力运行 HTTP 服务。 在微服务模式下，当容器绑定了 GRPCServerRegistrar 时，同时启动 gRPC 服务器。

func SelectCircuitBreakerProvider 

func SelectCircuitBreakerProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectCircuitBreakerProvider selects the circuit-breaker provider from config and governance mode.

SelectCircuitBreakerProvider 根据配置与治理模式选择熔断 provider。

func SelectCircuitBreakerProviderWithMode 

func SelectCircuitBreakerProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectCircuitBreakerProviderWithMode selects the circuit-breaker provider with an explicit governance mode.

SelectCircuitBreakerProviderWithMode 在显式治理模式下选择熔断 provider。

func SelectConfigSourceProvider 

func SelectConfigSourceProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectConfigSourceProvider selects the config-source provider from config.

SelectConfigSourceProvider 根据配置选择配置源 provider。

func SelectDTMProvider 

func SelectDTMProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectDTMProvider selects the DTM provider from config and enable flags.

SelectDTMProvider 根据配置与开关状态选择 DTM provider。

func SelectDiscoveryProvider 

func SelectDiscoveryProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectDiscoveryProvider selects the discovery provider from config.

SelectDiscoveryProvider 根据配置选择服务发现 provider。

func SelectDiscoveryProviderWithMode 

func SelectDiscoveryProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectDiscoveryProviderWithMode selects the discovery provider with an explicit governance mode.

SelectDiscoveryProviderWithMode 在显式治理模式下选择服务发现 provider。

func SelectDistributedLockProvider 

func SelectDistributedLockProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectDistributedLockProvider selects the distributed-lock provider from config and enable flags.

SelectDistributedLockProvider 根据配置与开关状态选择分布式锁 provider。

func SelectLoadSheddingProvider 

func SelectLoadSheddingProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectLoadSheddingProvider selects the load-shedding provider from config and governance mode.

SelectLoadSheddingProvider 根据配置与治理模式选择过载保护 provider。

func SelectLoadSheddingProviderWithMode 

func SelectLoadSheddingProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectLoadSheddingProviderWithMode selects the load-shedding provider with an explicit governance mode.

SelectLoadSheddingProviderWithMode 在显式治理模式下选择过载保护 provider。

func SelectMessageQueueProvider 

func SelectMessageQueueProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectMessageQueueProvider selects the message-queue provider from config and enable flags.

SelectMessageQueueProvider 根据配置与开关状态选择消息队列 provider。

func SelectMetadataProvider 

func SelectMetadataProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectMetadataProvider selects the metadata provider from config and governance mode.

SelectMetadataProvider 根据配置与治理模式选择 metadata provider。

func SelectMetadataProviderWithMode 

func SelectMetadataProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectMetadataProviderWithMode selects the metadata provider with an explicit governance mode.

SelectMetadataProviderWithMode 在显式治理模式下选择 metadata provider。

func SelectRPCProvider 

func SelectRPCProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectRPCProvider selects the RPC provider from config.

SelectRPCProvider 根据配置选择 RPC provider。

func SelectRPCProviderWithMode 

func SelectRPCProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectRPCProviderWithMode selects the RPC provider with an explicit governance mode.

SelectRPCProviderWithMode 在显式治理模式下选择 RPC provider。

func SelectRetryProvider 

func SelectRetryProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectRetryProvider selects the retry provider from config.

SelectRetryProvider 根据配置选择重试 provider。

func SelectRetryProviderWithMode 

func SelectRetryProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectRetryProviderWithMode selects the retry provider with an explicit governance mode.

SelectRetryProviderWithMode 在显式治理模式下选择重试 provider。

func SelectSelectorProvider 

func SelectSelectorProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectSelectorProvider selects the selector provider from config.

SelectSelectorProvider 根据配置选择 selector provider。

func SelectSelectorProviderWithMode 

func SelectSelectorProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectSelectorProviderWithMode selects the selector provider with an explicit governance mode.

SelectSelectorProviderWithMode 在显式治理模式下选择 selector provider。

func SelectServiceAuthProvider 

func SelectServiceAuthProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectServiceAuthProvider selects the service-auth provider from config and governance mode.

SelectServiceAuthProvider 根据配置与治理模式选择服务间认证 provider。

func SelectServiceAuthProviderWithMode 

func SelectServiceAuthProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectServiceAuthProviderWithMode selects the service-auth provider with an explicit governance mode.

SelectServiceAuthProviderWithMode 在显式治理模式下选择服务间认证 provider。

func SelectTracingProvider 

func SelectTracingProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectTracingProvider selects the tracing provider from config and governance mode.

SelectTracingProvider 根据配置与治理模式选择 tracing provider。

func SelectTracingProviderWithMode 

func SelectTracingProviderWithMode(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) runtimecontract.ServiceProvider

SelectTracingProviderWithMode selects the tracing provider with an explicit governance mode.

SelectTracingProviderWithMode 在显式治理模式下选择 tracing provider。

func SelectWebSocketProvider 

func SelectWebSocketProvider(cfg datacontract.Config) runtimecontract.ServiceProvider

SelectWebSocketProvider selects the WebSocket provider from config and enable flags.

SelectWebSocketProvider 根据配置与开关状态选择 WebSocket provider。

func SelectedMicroserviceProviders 

func SelectedMicroserviceProviders(cfg datacontract.Config) []runtimecontract.ServiceProvider

SelectedMicroserviceProviders returns the config-selected microservice capability providers. Does NOT process governance.disable/enable/providers.* overrides. For governance-aware selection, use SelectedMicroserviceProvidersWithOptions. Note: nil providers are filtered out to prevent nil panic in RegisterProviders.

SelectedMicroserviceProviders 返回由配置选择出的微服务能力 provider 集合。 不处理 governance.disable/enable/providers.* 覆盖。 需要治理覆盖的场景请使用 SelectedMicroserviceProvidersWithOptions。 注意：nil provider 会被过滤，防止 RegisterProviders 时 nil panic。

func SelectedMicroserviceProvidersWithOptions 

func SelectedMicroserviceProvidersWithOptions(cfg datacontract.Config, disabled, enabled []string, providerOverrides map[string]string) []runtimecontract.ServiceProvider

SelectedMicroserviceProvidersWithOptions returns governance-aware microservice providers. Processes governance.disable, governance.enable, and governance.providers.* overrides before selecting providers. Note: nil providers are filtered out to prevent nil panic in RegisterProviders.

SelectedMicroserviceProvidersWithOptions 返回带治理覆盖的微服务 provider 集合。 选择 provider 前处理 governance.disable、governance.enable 和 governance.providers.* 覆盖。 注意：nil provider 会被过滤，防止 RegisterProviders 时 nil panic。

func ServiceAuthProviders 

func ServiceAuthProviders() []runtimecontract.ServiceProvider

ServiceAuthProviders returns the providers used for service-to-service auth. Returns the governance-selected auth provider so that callers get the same provider that bootstrap would register.

ServiceAuthProviders 返回服务间认证使用的 provider 集合。 返回治理选择的鉴权 provider，与 bootstrap 注册的保持一致。

func StartGRPCServer 

func StartGRPCServer(c runtimecontract.Container, logger observabilitycontract.Logger) (transportcontract.RPCServer, error)

StartGRPCServer starts the gRPC server from the container when the container has a GRPCServerRegistrar bound. Returns the RPCServer if started, nil otherwise. This is used by the HTTP bootstrap to auto-start gRPC alongside HTTP in microservice mode.

StartGRPCServer 在容器中存在 GRPCServerRegistrar 时启动 gRPC 服务器。 返回启动的 RPCServer；如果容器中没有 gRPC 能力则返回 nil。 用于 HTTP bootstrap 在微服务模式下自动与 HTTP 一起启动 gRPC。

func ValidateCriticalConfig 

func ValidateCriticalConfig(cfg datacontract.Config) error

ValidateCriticalConfig 对关键配置节执行 fail-fast 校验。 校验策略：

  • 始终校验：app（HTTP 监听地址）、log（级别和格式）
  • 条件校验：server.http（当节存在时）、database（当节存在且非空时）
  • 跳过：tracing / redis 等可选节（缺失时不校验）

返回值：

  • nil：所有关键配置校验通过
  • error：包含所有校验失败项的聚合错误，每条错误带节名前缀

ValidateCriticalConfig performs fail-fast validation on critical config sections. Strategy:

  • Always validate: app (HTTP listen addr), log (level & format)
  • Conditional: server.http (when section exists), database (when section exists & non-empty)
  • Skip: optional sections like tracing, redis (not validated when absent)

Returns:

  • nil: all critical config sections passed validation
  • error: aggregated error with section name prefix on each field error

Types

type AppConfigSchema 

type AppConfigSchema struct {
	// Address 是 HTTP 服务监听地址，必填，例如 ":8080" 或 "0.0.0.0:8080"。
	//
	// Address is the HTTP listen address, required, e.g. ":8080" or "0.0.0.0:8080".
	Address string `validate:"required" mapstructure:"address"`
}

AppConfigSchema 对应 YAML 配置中的 app 节。 校验 app.address（HTTP 监听地址），这是服务启动的必要条件。

AppConfigSchema maps the "app" section in YAML config. Validates app.address (HTTP listen address), which is required for service startup.

type BackendKey 

type BackendKey string

BackendKey is a typed string representing a provider backend name. Use BackendXxx constants instead of raw string literals.

BackendKey 是表示 Provider 后端名称的类型化字符串。 请使用 BackendXxx 常量替代裸字符串字面量。 

const (
	// ── Common backends ────────────────────────────────
	// BackendNoop is the no-op backend shared by all capabilities.
	// BackendNoop 是所有能力共享的空实现后端。
	BackendNoop BackendKey = "noop"

	// BackendDefault is the default implementation backend.
	// BackendDefault 是默认实现后端。
	BackendDefault BackendKey = "default"

	// BackendLocal is the local implementation backend.
	// BackendLocal 是本地实现后端。
	BackendLocal BackendKey = "local"

	// ── ConfigSource backends ──────────────────────────
	BackendConsul  BackendKey = "consul"
	BackendEtcd    BackendKey = "etcd"
	BackendApollo  BackendKey = "apollo"
	BackendNacos   BackendKey = "nacos"
	BackendK8s     BackendKey = "kubernetes"
	BackendPolaris BackendKey = "polaris"

	// ── Discovery backends (shared with ConfigSource) ──
	BackendZookeeper   BackendKey = "zookeeper"
	BackendEureka      BackendKey = "eureka"
	BackendServiceComb BackendKey = "servicecomb"

	// ── Selector backends ──────────────────────────────
	BackendRandom  BackendKey = "random"
	BackendWRR     BackendKey = "wrr"
	BackendP2C     BackendKey = "p2c"
	BackendP2CEWMA BackendKey = "p2c_ewma"

	// ── RPC backends ───────────────────────────────────
	BackendHTTP BackendKey = "http"
	BackendGRPC BackendKey = "grpc"

	// ── Tracing backends ───────────────────────────────
	BackendOtel   BackendKey = "otel"
	BackendOTLP   BackendKey = "otlp"
	BackendStdout BackendKey = "stdout"

	// ── ServiceAuth backends ────────────────────────────
	BackendToken BackendKey = "token"
	BackendMTLS  BackendKey = "mtls"

	// ── CircuitBreaker backends ─────────────────────────
	BackendSentinel BackendKey = "sentinel"

	// ── LoadShedding backends ───────────────────────────
	BackendSemaphore BackendKey = "semaphore"

	// ── DTM backends ────────────────────────────────────
	BackendSDK    BackendKey = "sdk"
	BackendDTMSDK BackendKey = "dtmsdk"

	// ── MessageQueue backends ───────────────────────────
	BackendRedis    BackendKey = "redis"
	BackendKafka    BackendKey = "kafka"
	BackendRabbitMQ BackendKey = "rabbitmq"
	BackendRocketMQ BackendKey = "rocketmq"

	// ── WebSocket backends ─────────────────────────────
	BackendGWS BackendKey = "gws"
)

────────────────────────────────────────────────────── Provider backend keys Provider 后端名称常量 ──────────────────────────────────────────────────────

func (BackendKey) String 

func (k BackendKey) String() string

String implements fmt.Stringer.

type CapabilityKey 

type CapabilityKey string

CapabilityKey is a typed string representing a governance capability name. Use CapabilityXxx constants instead of raw string literals.

CapabilityKey 是表示治理能力名称的类型化字符串。 请使用 CapabilityXxx 常量替代裸字符串字面量。 

const (
	// CapabilityConfigSource is the governance key for configuration source.
	// CapabilityConfigSource 是配置源的治理能力名称。
	CapabilityConfigSource CapabilityKey = "configsource"

	// CapabilityDiscovery is the governance key for service discovery.
	// CapabilityDiscovery 是服务发现的治理能力名称。
	CapabilityDiscovery CapabilityKey = "discovery"

	// CapabilitySelector is the governance key for load balancing selector.
	// CapabilitySelector 是负载均衡选择器的治理能力名称。
	CapabilitySelector CapabilityKey = "selector"

	// CapabilityRPC is the governance key for RPC transport.
	// CapabilityRPC 是 RPC 传输的治理能力名称。
	CapabilityRPC CapabilityKey = "rpc"

	// CapabilityTracing is the governance key for distributed tracing.
	// CapabilityTracing 是分布式追踪的治理能力名称。
	CapabilityTracing CapabilityKey = "tracing"

	// CapabilityMetadata is the governance key for metadata propagation.
	// CapabilityMetadata 是元数据透传的治理能力名称。
	CapabilityMetadata CapabilityKey = "metadata"

	// CapabilityServiceAuth is the governance key for service authentication.
	// CapabilityServiceAuth 是服务鉴权的治理能力名称。
	CapabilityServiceAuth CapabilityKey = "serviceauth"

	// CapabilityCircuitBreaker is the governance key for circuit breaking.
	// CapabilityCircuitBreaker 是熔断的治理能力名称。
	CapabilityCircuitBreaker CapabilityKey = "circuitbreaker"

	// CapabilityLoadShedding is the governance key for load shedding.
	// CapabilityLoadShedding 是过载保护的治理能力名称。
	CapabilityLoadShedding CapabilityKey = "loadshedding"

	// CapabilityRetry is the governance key for retry.
	// CapabilityRetry 是重试的治理能力名称。
	CapabilityRetry CapabilityKey = "retry"

	// CapabilityDTM is the governance key for distributed transaction manager.
	// CapabilityDTM 是分布式事务管理器的治理能力名称。
	CapabilityDTM CapabilityKey = "dtm"

	// CapabilityMessageQueue is the governance key for message queue.
	// CapabilityMessageQueue 是消息队列的治理能力名称。
	CapabilityMessageQueue CapabilityKey = "message_queue"

	// CapabilityDistributedLock is the governance key for distributed lock.
	// CapabilityDistributedLock 是分布式锁的治理能力名称。
	CapabilityDistributedLock CapabilityKey = "distributed_lock"

	// CapabilityWebSocket is the governance key for WebSocket.
	// CapabilityWebSocket 是 WebSocket 的治理能力名称。
	CapabilityWebSocket CapabilityKey = "websocket"
)

────────────────────────────────────────────────────── Governance capability keys 治理能力名称常量 ──────────────────────────────────────────────────────

func AllCapabilities 

func AllCapabilities() []CapabilityKey

AllCapabilities returns all defined governance capability keys. Use this to iterate over capabilities without repeating the list.

AllCapabilities 返回所有已定义的治理能力名称常量。 用于遍历所有能力而无需重复列表。

func (CapabilityKey) String 

func (k CapabilityKey) String() string

String implements fmt.Stringer.

type DatabaseConfigSchema 

type DatabaseConfigSchema struct {
	// Driver 是数据库驱动，可选值：sqlite / mysql / postgres / pgx。
	// 当 DSN 非空时，Driver 也必须提供。
	//
	// Driver is the database driver. Valid values: sqlite / mysql / postgres / pgx.
	// When DSN is non-empty, Driver is also required.
	Driver string `validate:"required_with=DSN,oneof=sqlite mysql postgres pgx" mapstructure:"driver"`

	// DSN 是数据库连接字符串，当 Driver 非空时必须提供。
	//
	// DSN is the database connection string, required when Driver is non-empty.
	DSN string `validate:"required_with=Driver" mapstructure:"dsn"`
}

DatabaseConfigSchema 对应 YAML 配置中的 database 节。 数据库配置是条件必填：仅当 database 节存在且 driver/dsn 非空时才校验。 若用户未配置 database，校验自动跳过（不强制使用数据库）。

DatabaseConfigSchema maps the "database" section in YAML config. Database config is conditionally required: validated only when the database section exists and driver/dsn are non-empty. If the user does not configure database, validation is skipped (DB is optional).

type GRPCServiceOptions 

type GRPCServiceOptions struct {
	// ExtraProviders 是额外追加到容器中的 provider 列表。
	//
	// ExtraProviders 是额外追加到容器中的 provider 列表。
	ExtraProviders []runtimecontract.ServiceProvider

	// GovernanceMode 显式声明运行时治理模式。
	//
	// GovernanceMode 显式声明运行时治理模式。
	GovernanceMode string

	// GovernanceDisable 显式关闭的默认治理能力列表。
	//
	// GovernanceDisable 显式关闭的默认治理能力列表。
	GovernanceDisable []string

	// GovernanceEnable 显式开启的默认关闭治理能力列表。
	//
	// GovernanceEnable 显式开启的默认关闭治理能力列表。
	GovernanceEnable []string

	// GovernanceProviders 显式覆盖的治理 provider backend 映射。
	//
	// GovernanceProviders 显式覆盖的治理 provider backend 映射。
	GovernanceProviders map[string]string
}

GRPCServiceOptions describes the bootstrap options for the gRPC service mainline.

GRPCServiceOptions 描述 gRPC 服务主线的 bootstrap 选项。

type GRPCServiceRuntime 

type GRPCServiceRuntime struct {
	// App 是框架 Application 实例。
	//
	// App 是框架 Application 实例。
	App *framework.Application

	// Container 是运行时依赖注入容器。
	//
	// Container 是运行时依赖注入容器。
	Container runtimecontract.Container

	// Logger 是日志能力实例。
	//
	// Logger 是日志能力实例。
	Logger observabilitycontract.Logger

	// Server 是底层 gRPC 服务器实例，供用户在 setup 阶段注册 proto 服务。
	//
	// Server 是底层 gRPC 服务器实例，供用户在 setup 阶段注册 proto 服务。
	Server *grpc.Server

	// Registrar 是 gRPC 服务注册器，提供 RegisterProto 和 Server 方法。
	//
	// Registrar 是 gRPC 服务注册器，提供 RegisterProto 和 Server 方法。
	Registrar transportcontract.GRPCServerRegistrar

	// Config 是配置能力实例。
	//
	// Config 是配置能力实例。
	Config datacontract.Config

	// ServiceName 是当前服务名。
	//
	// ServiceName 是当前服务名。
	ServiceName string

	// GovernanceMode 是生效的治理模式。
	//
	// GovernanceMode 是生效的治理模式。
	GovernanceMode resiliencecontract.GovernanceMode

	// GovernanceSummary 是治理摘要信息。
	//
	// GovernanceSummary 是治理摘要信息。
	GovernanceSummary GovernanceSummary
}

GRPCServiceRuntime carries the assembled gRPC runtime state used during startup callbacks.

GRPCServiceRuntime 承载启动回调阶段使用的 gRPC runtime 状态。

func NewGRPCServiceRuntime 

func NewGRPCServiceRuntime(serviceName string, opts GRPCServiceOptions) (*GRPCServiceRuntime, error)

NewGRPCServiceRuntime builds the default gRPC runtime without starting the server.

NewGRPCServiceRuntime 构建默认 gRPC runtime，但不启动服务。

type GovernanceFeatureDecision 

type GovernanceFeatureDecision struct {
	Enabled bool   `json:"enabled"`
	Source  string `json:"source"`
	Reason  string `json:"reason"`
}

GovernanceFeatureDecision explains why one governance feature is enabled or disabled.

GovernanceFeatureDecision 解释某个治理 feature 为什么启用或未启用。

type GovernanceProviderDecision 

type GovernanceProviderDecision struct {
	Backend          string `json:"backend"`
	Source           string `json:"source"`
	Reason           string `json:"reason"`
	RequestedBackend string `json:"requested_backend,omitempty"`
	FallbackBackend  string `json:"fallback_backend,omitempty"`
	ConfigKey        string `json:"config_key,omitempty"`
}

GovernanceProviderDecision explains why one governance provider backend is currently active.

GovernanceProviderDecision 解释某个治理 provider backend 为什么最终生效。

type GovernanceProviderDefaults 

type GovernanceProviderDefaults struct {
	ConfigSource    string
	Discovery       string
	Selector        string
	RPC             string
	Tracing         string
	Metadata        string
	ServiceAuth     string
	CircuitBreaker  string
	LoadShedder     string
	Retry           string
	DTM             string
	MessageQueue    string
	DistributedLock string
	WebSocket       string
}

GovernanceProviderDefaults describes the mode-aware default provider backends.

GovernanceProviderDefaults 描述按治理模式生效的默认 provider backend。

func DefaultGovernanceProviderDefaults 

func DefaultGovernanceProviderDefaults(mode resiliencecontract.GovernanceMode) GovernanceProviderDefaults

DefaultGovernanceProviderDefaults returns the default provider backend bundle for one governance mode.

DefaultGovernanceProviderDefaults 返回某个治理模式对应的默认 provider backend 组合。

type GovernanceSummary 

type GovernanceSummary struct {
	Mode                 resiliencecontract.GovernanceMode           `json:"mode"`
	ModeSource           string                                      `json:"mode_source"`
	ModeReason           string                                      `json:"mode_reason"`
	EnabledFeatures      []string                                    `json:"enabled_features"`
	ModeDefaultFeatures  []string                                    `json:"mode_default_features"`
	DisabledByOverride   []string                                    `json:"disabled_by_override"`
	DisabledByConfig     []string                                    `json:"disabled_by_config"`
	DisabledByCode       []string                                    `json:"disabled_by_code"`
	EnabledByOverride    []string                                    `json:"enabled_by_override"`
	EnabledByConfig      []string                                    `json:"enabled_by_config"`
	EnabledByCode        []string                                    `json:"enabled_by_code"`
	FeatureDecisions     map[string]GovernanceFeatureDecision        `json:"feature_decisions"`
	ProviderBackends     map[string]string                           `json:"provider_backends"`
	ProviderDecisions    map[string]GovernanceProviderDecision       `json:"provider_decisions"`
	ConfigSnapshot       map[string]any                              `json:"config_snapshot"`
	ResolutionOrder      []string                                    `json:"resolution_order"`
	MiddlewareChainOrder []string                                    `json:"middleware_chain_order"`
	RPCClientChainOrder  []string                                    `json:"rpc_client_chain_order"`
	Defaults             *resiliencecontract.GovernanceDefaultsTable `json:"defaults,omitempty"`
}

GovernanceSummary describes the effective governance result for one runtime mode.

GovernanceSummary 描述某个运行模式下最终生效的治理结果。

func BuildGovernanceSummary 

func BuildGovernanceSummary(cfg datacontract.Config, mode resiliencecontract.GovernanceMode) GovernanceSummary

BuildGovernanceSummary builds the effective governance summary for one runtime mode and config snapshot.

BuildGovernanceSummary 根据运行模式与配置快照构建最终生效治理摘要。

func BuildGovernanceSummaryWithModeOverride 

func BuildGovernanceSummaryWithModeOverride(cfg datacontract.Config, mode resiliencecontract.GovernanceMode, modeOverride string) GovernanceSummary

BuildGovernanceSummaryWithModeOverride builds the effective governance summary and records whether mode came from code override.

BuildGovernanceSummaryWithModeOverride 构建最终治理生效摘要，并记录 mode 是否来自代码显式覆盖。

type HTTPServiceOptions 

type HTTPServiceOptions struct {
	ExtraProviders      []runtimecontract.ServiceProvider
	DisableRedis        bool
	DisableGorm         bool
	DisableMetrics      bool
	EnablePprof         bool
	GovernanceMode      string
	HTTPMode            string // HTTP 模式：contract 或 gin，与 GovernanceMode 正交
	GovernanceDisable   []string
	GovernanceEnable    []string
	GovernanceProviders map[string]string
}

HTTPServiceOptions describes the bootstrap options for the default HTTP mainline.

HTTPServiceOptions 描述默认 HTTP 主线的 bootstrap 选项。

type HTTPServiceRuntime 

type HTTPServiceRuntime struct {
	App               *framework.Application
	Container         runtimecontract.Container
	Logger            observabilitycontract.Logger
	Router            transportcontract.Router
	DB                *gormpkg.DB
	Redis             datacontract.Redis
	JWT               securitycontract.JWTService
	Config            datacontract.Config
	ServiceName       string
	GovernanceMode    resiliencecontract.GovernanceMode
	HTTPMode          resiliencecontract.HTTPMode // HTTP 模式维度：contract 或 gin
	GovernanceSummary GovernanceSummary

	// GRPCServer 是底层 gRPC 服务器实例，仅在微服务模式下可用。
	// 用户可在 setup 回调中使用此字段注册 proto 服务。
	// 单体模式下此字段为 nil，请使用 GetGRPCServer() 方法安全访问。
	//
	// GRPCServer is the underlying gRPC server instance, only available in microservice mode.
	// Users can use this field to register proto services in the setup callback.
	// In monolith mode this field is nil, use GetGRPCServer() method for safe access.
	GRPCServer *grpc.Server

	// GRPCServerRegistrar 是 gRPC 服务注册器，仅在微服务模式下可用。
	// 提供 RegisterProto 方法用于注册 proto 生成的服务实现。
	// 单体模式下此字段为 nil，请使用 GetGRPCServerRegistrar() 方法安全访问。
	//
	// GRPCServerRegistrar is the gRPC server registrar, only available in microservice mode.
	// Provides RegisterProto method for registering protobuf-generated service implementations.
	// In monolith mode this field is nil, use GetGRPCServerRegistrar() method for safe access.
	GRPCServerRegistrar transportcontract.GRPCServerRegistrar
}

HTTPServiceRuntime carries the assembled HTTP runtime state used during startup callbacks. In microservice mode, also carries the gRPC server instance for service registration.

IMPORTANT: All fields in this struct should be treated as read-only after the runtime is built. Modifying fields after setup may cause unpredictable behavior. The struct is exported for convenience, but users should only read from it, not write to it.

HTTPServiceRuntime 承载启动回调阶段使用的 HTTP runtime 状态。 在微服务模式下，同时承载 gRPC 服务器实例供服务注册使用。

重要提示：此结构体的所有字段在 runtime 构建后应视为只读。 在 setup 后修改字段可能导致不可预测的行为。结构体导出是为了便利， 但用户应只从中读取，不应写入。

func NewHTTPServiceRuntime 

func NewHTTPServiceRuntime(opts HTTPServiceOptions) (rt *HTTPServiceRuntime, retErr error)

NewHTTPServiceRuntime builds the default HTTP runtime without starting the server. Service name is read from config (app.name) automatically.

NewHTTPServiceRuntime 构建默认 HTTP runtime，但不启动服务。 服务名自动从配置 app.name 读取。

func (*HTTPServiceRuntime) GetCache 

func (rt *HTTPServiceRuntime) GetCache() datacontract.Cache

GetCache returns the cache capability. Panics if cache is not available.

GetCache 返回缓存能力。 如果缓存不可用则 panic。

func (*HTTPServiceRuntime) GetCron 

func (rt *HTTPServiceRuntime) GetCron() runtimecontract.Cron

GetCron returns the cron capability. Panics if cron is not available.

GetCron 返回定时任务能力。 如果定时任务不可用则 panic。

func (*HTTPServiceRuntime) GetDB 

func (rt *HTTPServiceRuntime) GetDB() (*gormpkg.DB, *sqlx.DB)

GetDB returns both Gorm and SQLX database handles. Panics if either is not available.

GetDB 返回 Gorm 和 SQLX 数据库句柄。 如果任一不可用则 panic。

func (*HTTPServiceRuntime) GetDistributedLock 

func (rt *HTTPServiceRuntime) GetDistributedLock() datacontract.DistributedLock

GetDistributedLock returns the distributed lock capability. Panics if distributed lock is not available.

GetDistributedLock 返回分布式锁能力。 如果分布式锁不可用则 panic。

func (*HTTPServiceRuntime) GetGRPCServer 

func (rt *HTTPServiceRuntime) GetGRPCServer() (*grpc.Server, error)

GetGRPCServer safely returns the gRPC server instance. Returns error in monolith mode where gRPC is not enabled.

GetGRPCServer 安全返回 gRPC 服务器实例。 在单体模式下（gRPC 未启用）返回错误。

func (*HTTPServiceRuntime) GetGRPCServerRegistrar 

func (rt *HTTPServiceRuntime) GetGRPCServerRegistrar() (transportcontract.GRPCServerRegistrar, error)

GetGRPCServerRegistrar safely returns the gRPC server registrar. Returns error in monolith mode where gRPC is not enabled.

GetGRPCServerRegistrar 安全返回 gRPC 服务注册器。 在单体模式下（gRPC 未启用）返回错误。

func (*HTTPServiceRuntime) GetGorm 

func (rt *HTTPServiceRuntime) GetGorm() *gormpkg.DB

GetGorm returns the Gorm database handle. Panics if Gorm is not available (DisableGorm=true).

GetGorm 返回 Gorm 数据库句柄。 如果 Gorm 不可用（DisableGorm=true）则 panic。

func (*HTTPServiceRuntime) GetMessagePublisher 

func (rt *HTTPServiceRuntime) GetMessagePublisher() integrationcontract.MessagePublisher

GetMessagePublisher returns the message publisher capability. Panics if message publisher is not available.

GetMessagePublisher 返回消息发布能力。 如果消息发布不可用则 panic。

func (*HTTPServiceRuntime) GetMessageSubscriber 

func (rt *HTTPServiceRuntime) GetMessageSubscriber() integrationcontract.MessageSubscriber

GetMessageSubscriber returns the message subscriber capability. Panics if message subscriber is not available.

GetMessageSubscriber 返回消息订阅能力。 如果消息订阅不可用则 panic。

func (*HTTPServiceRuntime) GetRedis 

func (rt *HTTPServiceRuntime) GetRedis() datacontract.Redis

GetRedis returns the Redis capability. Panics if Redis is not available (DisableRedis=true).

GetRedis 返回 Redis 能力。 如果 Redis 不可用（DisableRedis=true）则 panic。

func (*HTTPServiceRuntime) GetRetry 

func (rt *HTTPServiceRuntime) GetRetry() resiliencecontract.Retry

GetRetry returns the retry capability. Panics if retry is not available.

GetRetry 返回重试策略能力。 如果重试策略不可用则 panic。

func (*HTTPServiceRuntime) GetSQLX 

func (rt *HTTPServiceRuntime) GetSQLX() *sqlx.DB

GetSQLX returns the SQLX database handle. Panics if SQLX is not available.

GetSQLX 返回 SQLX 数据库句柄。 如果 SQLX 不可用则 panic。

func (*HTTPServiceRuntime) GetValidator 

func (rt *HTTPServiceRuntime) GetValidator() datacontract.Validator

GetValidator returns the validator capability. Panics if validator is not available.

GetValidator 返回参数校验能力。 如果参数校验不可用则 panic。

func (*HTTPServiceRuntime) MustGRPCServer 

func (rt *HTTPServiceRuntime) MustGRPCServer() *grpc.Server

MustGRPCServer returns the gRPC server instance or panics if not available. Use only when gRPC is guaranteed to be enabled (microservice mode).

MustGRPCServer 返回 gRPC 服务器实例，不可用时 panic。 仅在确定 gRPC 已启用（微服务模式）时使用。

func (*HTTPServiceRuntime) MustGRPCServerRegistrar 

func (rt *HTTPServiceRuntime) MustGRPCServerRegistrar() transportcontract.GRPCServerRegistrar

MustGRPCServerRegistrar returns the gRPC server registrar or panics if not available. Use only when gRPC is guaranteed to be enabled (microservice mode).

MustGRPCServerRegistrar 返回 gRPC 服务注册器，不可用时 panic。 仅在确定 gRPC 已启用（微服务模式）时使用。

type LogConfigSchema 

type LogConfigSchema struct {
	// Level 是日志级别，必填，可选值：debug / info / warn / error。
	//
	// Level is the log level, required. Valid values: debug / info / warn / error.
	Level string `validate:"required,oneof=debug info warn error" mapstructure:"level"`

	// Format 是日志输出格式，必填，可选值：console / json。
	//
	// Format is the log output format, required. Valid values: console / json.
	Format string `validate:"required,oneof=console json" mapstructure:"format"`
}

LogConfigSchema 对应 YAML 配置中的 log 节。 日志级别和格式是服务可观测性的基础，缺失会导致日志行为不可预期。

LogConfigSchema maps the "log" section in YAML config. Log level and format are foundational for observability; missing values lead to unpredictable logging behavior.

type RedisConfigSchema 

type RedisConfigSchema struct {
	// Addr 是 Redis 连接地址，使用 Redis 时必填。
	Addr string `validate:"required" mapstructure:"addr"`
}

RedisConfigSchema 对应 YAML 配置中的 redis 节。 仅当 redis 段存在且 addr 非空时校验。

RedisConfigSchema maps the "redis" section in YAML config. Validated only when the section exists and addr is non-empty.

type ServerHTTPConfigSchema 

type ServerHTTPConfigSchema struct {
	// Addr 是 HTTP 服务监听地址，必填（当 server.http 节存在时）。
	//
	// Addr is the HTTP listen address, required when server.http section is present.
	Addr string `validate:"required" mapstructure:"addr"`
}

ServerHTTPConfigSchema 对应 YAML 配置中的 server.http 节。 当用户显式配置 server.http 时，addr 必须提供。

ServerHTTPConfigSchema maps the "server.http" section in YAML config. When server.http is explicitly configured, addr must be provided.

type ServiceAuthConfigSchema 

type ServiceAuthConfigSchema struct {
	// Backend 是服务间认证后端，启用时必填，可选值：token / mtls / noop。
	Backend string `validate:"required,oneof=token mtls noop" mapstructure:"backend"`
}

ServiceAuthConfigSchema 对应 YAML 配置中的 service_auth 节。 仅当 service_auth.enabled=true 时校验。

ServiceAuthConfigSchema maps the "service_auth" section in YAML config. Validated only when service_auth.enabled=true.

type TracingConfigSchema 

type TracingConfigSchema struct {
	// Backend 是追踪后端，启用时必填，可选值：otel / zipkin / noop。
	Backend string `validate:"required,oneof=otel otlp grpc http stdout noop" mapstructure:"backend"`

	// ServiceName 是追踪服务名，启用时必填。
	ServiceName string `validate:"required" mapstructure:"service_name"`
}

TracingConfigSchema 对应 YAML 配置中的 tracing 节。 仅当 tracing.enabled=true 时校验，缺失或关闭时跳过。

TracingConfigSchema maps the "tracing" section in YAML config. Validated only when tracing.enabled=true; skipped when absent or disabled.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.