application

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: May 21, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package application provides application startup entrypoints for gorp framework. Exposes container-backed capability accessors and transport convenience APIs. Offers stable helpers for service identity propagation and gRPC metadata access.

应用启动包提供 gorp 框架的应用启动入口。 暴露基于容器的能力获取入口和 transport 便捷 API。 提供稳定的服务身份透传助手和 gRPC 元数据读取助手。

Package application provides application startup entrypoints for gorp framework. This file defines stable startup and assembly error sentinels. Let callers use errors.Is against well-known bootstrap and runtime failures.

应用启动包提供 gorp 框架的应用启动入口。 本文件定义稳定的启动与装配错误哨兵值。 让调用方可以通过 errors.Is 判断已知的启动与运行时失败。

Package application provides application startup entrypoints for gorp framework. This file centralizes internal helpers for startup flow normalization. Normalizes option handling and startup context checks before runtime construction.

应用启动包提供 gorp 框架的应用启动入口。 本文件集中管理启动流程的内部辅助逻辑。 在 runtime 构建前统一处理选项归一化与启动 context 检查。

Package application provides application startup entrypoints for gorp framework. This file exposes startup option builders for HTTP mode, providers, hooks. Lets business code declare startup configuration succinctly.

应用启动包提供 gorp 框架的应用启动入口。 本文件暴露启动选项构造入口，包括 HTTP 模式、provider、钩子。 让业务代码可以简洁声明启动配置。

Eg: 

application.Run("my-service",
    application.WithProviders(configprovider.NewProvider()),
    application.WithHTTPRoutes(registerRoutes),
)

HTTP is enabled by default. Use HTTP() only when you need HTTPServiceOptions. Use WithoutHTTP() to explicitly disable the HTTP mainline.

HTTP 默认已启用。仅当需要传入 HTTPServiceOptions 时才调用 HTTP()。 使用 WithoutHTTP() 可显式关闭 HTTP 主线。

Package application provides application startup entrypoints for gorp framework. This file exposes the main startup entrypoints: Run and Build. Supports direct boot and runtime-only build workflows for HTTP services.

应用启动包提供 gorp 框架的应用启动入口。 本文件暴露主启动入口：Run 和 Build。 支持直接启动和仅构建 runtime 的 HTTP 服务工作流。

Package application provides application startup entrypoints for gorp framework. This file holds shared types and option contracts for startup helpers. Provides runtime aliases, callback contracts, and internal startup config.

应用启动包提供 gorp 框架的应用启动入口。 本文件承载启动辅助所需的共享类型与选项契约。 提供 runtime 别名、回调契约和内部启动配置。

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoServiceDeclared indicates that no runnable service has been declared.
	//
	// ErrNoServiceDeclared 表示没有声明可运行服务。
	ErrNoServiceDeclared = errors.New("application: no service declared")

	// ErrHTTPRouteRegistrationFailed indicates that HTTP route registration failed.
	//
	// ErrHTTPRouteRegistrationFailed 表示 HTTP 路由注册失败。
	ErrHTTPRouteRegistrationFailed = errors.New("application: http route registration failed")

	// ErrHTTPRuntimeUnavailable indicates that the HTTP runtime is unavailable during route setup.
	//
	// ErrHTTPRuntimeUnavailable 表示 HTTP 路由注册阶段缺少可用 runtime。
	ErrHTTPRuntimeUnavailable = errors.New("application: http runtime unavailable")

	// ErrSetupFailed indicates that the setup callback failed.
	//
	// ErrSetupFailed 表示 setup 回调执行失败。
	ErrSetupFailed = errors.New("application: setup failed")

	// ErrMigrateFailed indicates that the migrate callback failed.
	//
	// ErrMigrateFailed 表示 migrate 回调执行失败。
	ErrMigrateFailed = errors.New("application: migrate failed")

	// ErrStartupCanceled indicates that startup was canceled before boot completed.
	//
	// ErrStartupCanceled 表示启动前 context 已取消。
	ErrStartupCanceled = errors.New("application: startup canceled")

	// ErrHTTPServiceRunFailed indicates that booting the default HTTP service failed.
	//
	// ErrHTTPServiceRunFailed 表示 HTTP 服务启动失败。
	ErrHTTPServiceRunFailed = errors.New("application: http service run failed")

	// ErrHTTPRuntimeBuildFailed indicates that building the HTTP runtime failed.
	//
	// ErrHTTPRuntimeBuildFailed 表示 HTTP runtime 构建失败。
	ErrHTTPRuntimeBuildFailed = errors.New("application: http runtime build failed")

	// ErrGRPCServiceRunFailed indicates that booting the gRPC service failed.
	//
	// ErrGRPCServiceRunFailed 表示 gRPC 服务启动失败。
	ErrGRPCServiceRunFailed = errors.New("application: grpc service run failed")

	// ErrGRPCRuntimeBuildFailed indicates that building the gRPC runtime failed.
	//
	// ErrGRPCRuntimeBuildFailed 表示 gRPC runtime 构建失败。
	ErrGRPCRuntimeBuildFailed = errors.New("application: grpc runtime build failed")
)

Functions

func FromServiceIdentity 

func FromServiceIdentity(ctx context.Context) (*securitycontract.ServiceIdentity, bool)

FromServiceIdentity reads service identity from the context.

FromServiceIdentity 读取上下文中的服务身份。

func GetGRPCRequestID 

func GetGRPCRequestID(ctx context.Context) string

GetGRPCRequestID reads the request id from a gRPC context.

GetGRPCRequestID 从 gRPC context 读取 request id。

func GetGRPCTraceID 

func GetGRPCTraceID(ctx context.Context) string

GetGRPCTraceID reads the trace id from a gRPC context.

GetGRPCTraceID 从 gRPC context 读取 trace id。

func MakeDistributedLock 

func MakeDistributedLock(c runtimecontract.Container) (datacontract.DistributedLock, error)

MakeDistributedLock returns the distributed lock capability from the container.

MakeDistributedLock 获取分布式锁能力。

func MakeGRPCConnFactory 

func MakeGRPCConnFactory(c runtimecontract.Container) (transportcontract.GRPCConnFactory, error)

MakeGRPCConnFactory returns the proto-first gRPC connection factory from the container.

MakeGRPCConnFactory 获取 Proto-first gRPC 连接工厂。

func MakeGRPCServerRegistrar 

func MakeGRPCServerRegistrar(c runtimecontract.Container) (transportcontract.GRPCServerRegistrar, error)

MakeGRPCServerRegistrar returns the proto-first gRPC server registrar from the container.

MakeGRPCServerRegistrar 获取 Proto-first gRPC 服务端注册器。

func MakeMessagePublisher 

func MakeMessagePublisher(c runtimecontract.Container) (integrationcontract.MessagePublisher, error)

MakeMessagePublisher returns the message publishing capability from the container.

MakeMessagePublisher 获取消息发布能力。

func MakeMessageSubscriber 

func MakeMessageSubscriber(c runtimecontract.Container) (integrationcontract.MessageSubscriber, error)

MakeMessageSubscriber returns the message subscription capability from the container.

MakeMessageSubscriber 获取消息订阅能力。

func Run 

func Run(options ...Option) error

Run boots the default HTTP mainline with application options. Service name is read from config file (app.name) automatically.

说明：业务运行入口仍是项目自己的 main；application 只提供启动装配 helper。 Run 启动默认 HTTP 主线，服务名自动从配置文件 app.name 读取。

Example: 

err := application.Run(
    application.HTTP(),
    application.WithProviders(myProvider),
    application.WithHTTPRoutes(func(router transportcontract.Router, c runtimecontract.Container) error {
        registerRoutes(router)
        return nil
    }),
)

func RunContext 

func RunContext(ctx context.Context, options ...Option) error

RunContext boots the default mainline with an explicit context. Service name is read from config file (app.name) automatically.

当前语义：仅在启动前检查取消，运行中关闭流程仍由 bootstrap 处理。 RunContext 使用显式 context 启动默认主线，服务名从配置自动读取。

func Start 

func Start(options ...Option) error

Start is an alias of Run.

Start 是 Run 的同义入口。

func WithServiceIdentity 

func WithServiceIdentity(ctx context.Context, identity *securitycontract.ServiceIdentity) context.Context

WithServiceIdentity writes service identity into the context.

WithServiceIdentity 把服务身份写入上下文。

Example: 

ctx = application.WithServiceIdentity(ctx, identity)

Types

type GRPCRuntime 

type GRPCRuntime = bootstrap.GRPCServiceRuntime

GRPCRuntime is the startup runtime exposed to application gRPC callbacks.

GRPCRuntime 是 application 回调使用的 gRPC 启动上下文。

type HTTPRouteRegistrar 

type HTTPRouteRegistrar func(router transportcontract.Router, container runtimecontract.Container) error

HTTPRouteRegistrar defines the default HTTP route registration callback contract.

HTTPRouteRegistrar 定义默认 HTTP 路由注册回调契约。

type HTTPRuntime 

type HTTPRuntime = bootstrap.HTTPServiceRuntime

HTTPRuntime is the startup runtime exposed to application callbacks.

HTTPRuntime 是 application 回调使用的启动上下文。

func Build 

func Build(options ...Option) (*HTTPRuntime, error)

Build is an alias of BuildHTTPRuntime.

Build 是 BuildHTTPRuntime 的同义入口。

func BuildHTTPRuntime 

func BuildHTTPRuntime(options ...Option) (*HTTPRuntime, error)

BuildHTTPRuntime builds the startup runtime without starting listeners. Service name is read from config (app.name) automatically.

BuildHTTPRuntime 仅构建启动上下文，不启动监听。 服务名自动从配置 app.name 读取。

Example: 

rt, err := application.BuildHTTPRuntime(application.HTTP())
if err != nil {
    return err
}
defer rt.Container.Close()

type HTTPServiceOptions 

type HTTPServiceOptions struct {
	DisableRedis        bool
	DisableGorm         bool
	DisableMetrics      bool
	GovernanceMode      resiliencecontract.GovernanceMode
	HTTPMode            resiliencecontract.HTTPMode // HTTP 模式维度：contract 或 gin
	GovernanceDisable   []string
	GovernanceEnable    []string
	GovernanceProviders map[string]string
}

HTTPServiceOptions is the minimal HTTP options view exposed by the application package.

HTTPServiceOptions 是 application 包暴露的最小 HTTP 选项视图。

type MigrateFunc 

type MigrateFunc func(*HTTPRuntime) error

MigrateFunc defines the migration callback contract.

MigrateFunc 定义迁移回调契约。

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option describes an application startup option.

Option 用于声明 application 启动配置。

func GRPC 

func GRPC() Option

GRPC declares that the gRPC service should be started alongside the HTTP mainline. This enables the gRPC server in the HTTPServiceRuntime, allowing users to register proto services via rt.GRPCServer in the setup callback.

GRPC 声明在 HTTP 主线之外同时启动 gRPC 服务。 这会在 HTTPServiceRuntime 中启用 gRPC 服务器，允许用户在 setup 回调中 通过 rt.GRPCServer 注册 proto 服务。

Example: 

gorp.Run("user-service",
    gorp.HTTP(),
    gorp.GRPC(),
    gorp.WithMicroMode(),
    gorp.WithSetup(func(rt *gorp.HTTPRuntime) error {
        pb.RegisterUserServiceServer(rt.GRPCServer, userService)
        return nil
    }),
)

func HTTP 

func HTTP(opts ...HTTPServiceOptions) Option

HTTP declares HTTP service options. The HTTP mainline is enabled by default, so calling HTTP() without arguments is unnecessary. Use HTTP() only when you need to pass HTTPServiceOptions (e.g. to disable built-in Redis/Gorm, or override governance settings). Use WithoutHTTP() to explicitly disable HTTP.

HTTP 声明 HTTP 服务选项。HTTP 主线默认已启用，无参调用 HTTP() 是冗余的。 仅当需要传入 HTTPServiceOptions 时才调用（例如禁用内置 Redis/Gorm，或覆盖治理配置）。 使用 WithoutHTTP() 可显式关闭 HTTP 主线。

Example: 

// 传参时才需要调用 HTTP() / Only needed when passing options:
application.HTTP(application.HTTPServiceOptions{
    DisableRedis: true,
})

func Module 

func Module(providers ...ServiceProvider) Option

Module declares providers for a single module.

Module 声明单个模块的 providers。

func Modules 

func Modules(groups ...[]ServiceProvider) Option

Modules declares providers for a group of modules.

Modules 声明一组模块 providers。

func WithContractHTTPMode 

func WithContractHTTPMode() Option

WithContractHTTPMode selects the gorp.Context contract abstraction.

WithContractHTTPMode 选择 gorp.Context 契约抽象。

func WithGinHTTPMode 

func WithGinHTTPMode() Option

WithGinHTTPMode selects the native gin.Context mode.

WithGinHTTPMode 选择原生 gin.Context 模式。

func WithGovernanceDisabled 

func WithGovernanceDisabled(names ...string) Option

WithGovernanceDisabled explicitly disables one or more default governance capabilities.

WithGovernanceDisabled 显式关闭一个或多个默认治理能力。

func WithGovernanceEnabled 

func WithGovernanceEnabled(names ...string) Option

WithGovernanceEnabled explicitly enables one or more governance capabilities that are off by default. This is the symmetric counterpart of WithGovernanceDisabled. When the same feature appears in both enable and disable, disable takes precedence.

WithGovernanceEnabled 显式开启一个或多个默认关闭的治理能力。 这是 WithGovernanceDisabled 的对称入口。 当同一 feature 同时出现在 enable 和 disable 中时，disable 生效。

func WithGovernanceMode 

func WithGovernanceMode(mode resiliencecontract.GovernanceMode) Option

WithGovernanceMode declares the startup governance mode explicitly.

WithGovernanceMode 显式声明启动治理模式。

func WithGovernanceProvider 

func WithGovernanceProvider(name, backend string) Option

WithGovernanceProvider explicitly overrides one governance provider backend.

WithGovernanceProvider 显式覆盖一个治理 provider backend。

func WithHTTPMode 

func WithHTTPMode(mode resiliencecontract.HTTPMode) Option

WithHTTPMode declares the HTTP handling mode explicitly. HTTPMode controls handler signature style (gorp.Context vs gin.Context).

WithHTTPMode 显式声明 HTTP 处理抽象模式。 HTTPMode 控制 handler 签名风格（gorp.Context vs gin.Context）。

func WithHTTPRoutes 

func WithHTTPRoutes(register HTTPRouteRegistrar) Option

WithHTTPRoutes declares the default HTTP route registration callback.

WithHTTPRoutes 声明默认 HTTP 路由注册回调。

Example: 

application.WithHTTPRoutes(func(router transportcontract.Router, c runtimecontract.Container) error {
    api := router.Group("/api")
    api.GET("/ping", pingHandler)
    return nil
})

func WithMicroGovernance 

func WithMicroGovernance() Option

WithMicroGovernance selects microservice governance and HTTP contract mode.

WithMicroGovernance 选择微服务治理 + HTTP 契约模式。

func WithMicroMode 

func WithMicroMode() Option

WithMicroMode selects the microservice governance mainline.

WithMicroMode 选择微服务治理主线。

func WithMigrate 

func WithMigrate(fn MigrateFunc) Option

WithMigrate declares a migration callback.

WithMigrate 声明迁移回调。

Example: 

application.WithMigrate(func(rt *application.HTTPRuntime) error {
    return migrateSchema(rt.Container)
})

func WithModule 

func WithModule(providers ...ServiceProvider) Option

WithModule is the explicit named alias of Module.

WithModule 是 Module 的显式命名入口。

func WithMonoGovernance 

func WithMonoGovernance() Option

WithMonoGovernance selects mono governance (HTTP mode left to default or explicit).

WithMonoGovernance 选择单体治理（HTTP 模式由默认值或显式参数决定）。

func WithMonoMode 

func WithMonoMode() Option

WithMonoMode selects the lightweight mono governance mode.

WithMonoMode 选择轻量单体治理模式。

func WithProviders 

func WithProviders(providers ...ServiceProvider) Option

WithProviders appends provider declarations without changing the startup semantics.

WithProviders 追加 providers 声明，不改变底层启动语义。

Example: 

application.WithProviders(
    configprovider.NewProvider(),
    cacheprovider.NewProvider(),
)

func WithSetup 

func WithSetup(fn SetupFunc) Option

WithSetup declares a setup callback.

WithSetup 声明装配回调。

Example: 

application.WithSetup(func(rt *application.HTTPRuntime) error {
    return registerHTTP(rt.Router)
})

func WithoutHTTP 

func WithoutHTTP() Option

WithoutHTTP explicitly disables the default HTTP declaration.

WithoutHTTP 显式关闭默认 HTTP 声明。

type ServiceProvider 

type ServiceProvider = runtimecontract.ServiceProvider

ServiceProvider reuses the provider declaration from the runtime contract.

ServiceProvider 复用 runtime contract 中的 provider 声明。

type SetupFunc 

type SetupFunc func(*HTTPRuntime) error

SetupFunc defines the startup setup callback contract.

SetupFunc 定义启动装配回调契约。

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.