servicecontextx

Documentation

Overview

Package servicecontextx provides a tiny typed dependency container for generated or hand-written service entrypoints.

It is inspired by go-zero's ServiceContext pattern: handlers/logic should not construct clients, stores or guards directly. Instead, application startup wires dependencies once and passes a ServiceContext through the route layer.

Index

• func Get[T any](c *Context) (T, bool)
• func GetAs[T any](c *Context, name string) (T, bool)
• func MustGet[T any](c *Context) T
• func MustGetAs[T any](c *Context, name string) T
• func MustTypedClient[T any](c *Context, name string) T
• func TypedClient[T any](c *Context, name string) (T, bool)
• type ClientKind
• type ClientRef
  • func Client(c *Context, name string) (ClientRef, bool)
  • func MustClient(c *Context, name string) ClientRef
• type Context
  • func MustNew() *Context
  • func New() *Context
  • func (c *Context) Close() error
  • func (c *Context) MustPut(dep any)
  • func (c *Context) MustPutAs(name string, dep any)
  • func (c *Context) MustPutClient(ref ClientRef)
  • func (c *Context) OnClose(fn func() error)
  • func (c *Context) Put(dep any) error
  • func (c *Context) PutAs(name string, dep any) error
  • func (c *Context) PutClient(ref ClientRef) error

Functions

func Get

func Get[T any](c *Context) (T, bool)

Get returns a dependency by concrete type.

func GetAs

func GetAs[T any](c *Context, name string) (T, bool)

GetAs returns a named dependency.

func MustGet

func MustGet[T any](c *Context) T

MustGet returns a dependency by concrete type or panics. It should only be used during startup or in generated code where missing dependencies are programming errors.

func MustGetAs

func MustGetAs[T any](c *Context, name string) T

MustGetAs returns a named dependency or panics.

func MustTypedClient

func MustTypedClient[T any](c *Context, name string) T

MustTypedClient returns the generated client value for name or panics.

func TypedClient

func TypedClient[T any](c *Context, name string) (T, bool)

TypedClient returns the generated client value for name.

Types

type ClientKind

type ClientKind string

ClientKind classifies a dependency that talks to another service. The value is intentionally string-based so projects can add custom kinds without a framework release.

const (
	ClientKindGRPC ClientKind = "grpc"
	ClientKindHTTP ClientKind = "http"
)

type ClientRef

type ClientRef struct {
	Name     string
	Kind     ClientKind
	Target   string
	Client   any
	Timeout  time.Duration
	Metadata map[string]string
}

ClientRef describes an internal service client stored in ServiceContext. It keeps the generated client value plus enough metadata for logs, health checks, and generated code to understand how the client was wired.

func Client

func Client(c *Context, name string) (ClientRef, bool)

Client returns a named client descriptor.

func MustClient

func MustClient(c *Context, name string) ClientRef

MustClient returns a named client descriptor or panics.

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context stores shared service dependencies by their concrete type or by a caller-supplied name.

The container is intentionally small. It is not a full DI framework; it is a stable handoff point for generated route/logic code and for business modules that want go-zero-style dependency ownership without importing go-zero.

func MustNew

func MustNew() *Context

MustNew returns a service context and panics only if future construction options fail. It exists to mirror common service bootstrap style.

func New

func New() *Context

New creates an empty service context.

func (*Context) Close

func (c *Context) Close() error

Close executes registered shutdown hooks in reverse order and returns the first error, if any.

func (*Context) MustPut

func (c *Context) MustPut(dep any)

MustPut registers dep by concrete type and panics on programmer error.

func (*Context) MustPutAs

func (c *Context) MustPutAs(name string, dep any)

MustPutAs registers dep under name and panics on programmer error.

func (*Context) MustPutClient

func (c *Context) MustPutClient(ref ClientRef)

MustPutClient stores a named client and panics on programmer error.

func (*Context) OnClose

func (c *Context) OnClose(fn func() error)

OnClose registers a shutdown hook. Hooks run in reverse registration order.

func (*Context) Put

func (c *Context) Put(dep any) error

Put registers dep by its concrete dynamic type.

func (*Context) PutAs

func (c *Context) PutAs(name string, dep any) error

PutAs registers dep under a named key. Named dependencies are useful when a service has multiple values of the same concrete type, such as two RPC clients.

func (*Context) PutClient

func (c *Context) PutClient(ref ClientRef) error

PutClient stores a named internal service client. Generated Gateway/BFF logic should prefer named clients over constructing gRPC/HTTP clients inline.