From c013ff6d5e240d733cddfcbc372d46e10e79ac0b Mon Sep 17 00:00:00 2001 From: Abhinav Gupta Date: Tue, 20 Feb 2024 11:56:20 -0800 Subject: [PATCH] Move advanced features to package documentation (#1163) The documentation for parameter structs, result structs, named values, optional values, value groups, etc. is currently scattered between In and Out. First, on the logistics end: this has made it impossible to link to some of these docs because they share the same hadings: https://pkg.go.dev/go.uber.org/fx#hdr-Named_Values goes to the named values section of fx.In. It's not possible to link to the named values section of the fx.Out struct (which is also called Named Values). More importantly, from the doc readability point of view, jumping between In and Out is annoying and doesn't make for good reading. This PR moves these to the package-level docs and improves the flow of how this information is presented: First, we introduce parameter and result structs. Then we weave through the two introducing various topics: Producing named values Result structs Consuming named values Parameter structs Optional dependencies Parameter structs Producing value groups Result structs Consuming value groups Parameter structs Soft value groups Parameter structs Value group flattening Result structs Unexported fields Parameter structs This makes the story of these topics a bit easier to follow. In the future, we can introduce annotation right after parameter and result structs, or between value groups and soft value groups. Note that this does not touch on the core operations (provide, invoke, decorate). It's just moving existing documentation around. --- doc.go | 327 ++++++++++++++++++++++++++++++++++++++++++++++++++- inout.go | 353 +++---------------------------------------------------- 2 files changed, 340 insertions(+), 340 deletions(-) diff --git a/doc.go b/doc.go index 590fe8d39..4ee2227ac 100644 --- a/doc.go +++ b/doc.go @@ -27,13 +27,334 @@ // to use struct tags or embed special types, so Fx automatically works well // with most Go packages. // -// Basic usage is explained in the package-level example below. If you're new -// to Fx, start there! Advanced features, including named instances, optional -// parameters, and value groups, are explained under the In and Out types. +// # Basic usage +// +// Basic usage is explained in the package-level example. +// If you're new to Fx, start there! +// +// Advanced features, including named instances, optional parameters, +// and value groups, are explained in this section further down. // // # Testing Fx Applications // // To test functions that use the Lifecycle type or to write end-to-end tests // of your Fx application, use the helper functions and types provided by the // go.uber.org/fx/fxtest package. +// +// # Parameter Structs +// +// Fx constructors declare their dependencies as function parameters. This can +// quickly become unreadable if the constructor has a lot of dependencies. +// +// func NewHandler(users *UserGateway, comments *CommentGateway, posts *PostGateway, votes *VoteGateway, authz *AuthZGateway) *Handler { +// // ... +// } +// +// To improve the readability of constructors like this, create a struct that +// lists all the dependencies as fields and change the function to accept that +// struct instead. The new struct is called a parameter struct. +// +// Fx has first class support for parameter structs: any struct embedding +// fx.In gets treated as a parameter struct, so the individual fields in the +// struct are supplied via dependency injection. Using a parameter struct, we +// can make the constructor above much more readable: +// +// type HandlerParams struct { +// fx.In +// +// Users *UserGateway +// Comments *CommentGateway +// Posts *PostGateway +// Votes *VoteGateway +// AuthZ *AuthZGateway +// } +// +// func NewHandler(p HandlerParams) *Handler { +// // ... +// } +// +// Though it's rarelly necessary to mix the two, constructors can receive any +// combination of parameter structs and parameters. +// +// func NewHandler(p HandlerParams, l *log.Logger) *Handler { +// // ... +// } +// +// # Result Structs +// +// Result structs are the inverse of parameter structs. +// These structs represent multiple outputs from a +// single function as fields. Fx treats all structs embedding fx.Out as result +// structs, so other constructors can rely on the result struct's fields +// directly. +// +// Without result structs, we sometimes have function definitions like this: +// +// func SetupGateways(conn *sql.DB) (*UserGateway, *CommentGateway, *PostGateway, error) { +// // ... +// } +// +// With result structs, we can make this both more readable and easier to +// modify in the future: +// +// type Gateways struct { +// fx.Out +// +// Users *UserGateway +// Comments *CommentGateway +// Posts *PostGateway +// } +// +// func SetupGateways(conn *sql.DB) (Gateways, error) { +// // ... +// } +// +// # Named Values +// +// Some use cases require the application container to hold multiple values of +// the same type. +// +// A constructor that produces a result struct can tag any field with +// `name:".."` to have the corresponding value added to the graph under the +// specified name. An application may contain at most one unnamed value of a +// given type, but may contain any number of named values of the same type. +// +// type ConnectionResult struct { +// fx.Out +// +// ReadWrite *sql.DB `name:"rw"` +// ReadOnly *sql.DB `name:"ro"` +// } +// +// func ConnectToDatabase(...) (ConnectionResult, error) { +// // ... +// return ConnectionResult{ReadWrite: rw, ReadOnly: ro}, nil +// } +// +// Similarly, a constructor that accepts a parameter struct can tag any field +// with `name:".."` to have the corresponding value injected by name. +// +// type GatewayParams struct { +// fx.In +// +// WriteToConn *sql.DB `name:"rw"` +// ReadFromConn *sql.DB `name:"ro"` +// } +// +// func NewCommentGateway(p GatewayParams) (*CommentGateway, error) { +// // ... +// } +// +// Note that both the name AND type of the fields on the +// parameter struct must match the corresponding result struct. +// +// # Optional Dependencies +// +// Constructors often have optional dependencies on some types: if those types are +// missing, they can operate in a degraded state. Fx supports optional +// dependencies via the `optional:"true"` tag to fields on parameter structs. +// +// type UserGatewayParams struct { +// fx.In +// +// Conn *sql.DB +// Cache *redis.Client `optional:"true"` +// } +// +// If an optional field isn't available in the container, the constructor +// receives the field's zero value. +// +// func NewUserGateway(p UserGatewayParams, log *log.Logger) (*UserGateway, error) { +// if p.Cache == nil { +// log.Print("Caching disabled") +// } +// // ... +// } +// +// Constructors that declare optional dependencies MUST gracefully handle +// situations in which those dependencies are absent. +// +// The optional tag also allows adding new dependencies without breaking +// existing consumers of the constructor. +// +// The optional tag may be combined with the name tag to declare a named +// value dependency optional. +// +// type GatewayParams struct { +// fx.In +// +// WriteToConn *sql.DB `name:"rw"` +// ReadFromConn *sql.DB `name:"ro" optional:"true"` +// } +// +// func NewCommentGateway(p GatewayParams, log *log.Logger) (*CommentGateway, error) { +// if p.ReadFromConn == nil { +// log.Print("Warning: Using RW connection for reads") +// p.ReadFromConn = p.WriteToConn +// } +// // ... +// } +// +// # Value Groups +// +// To make it easier to produce and consume many values of the same type, Fx +// supports named, unordered collections called value groups. +// +// Constructors can send values into value groups by returning a result struct +// tagged with `group:".."`. +// +// type HandlerResult struct { +// fx.Out +// +// Handler Handler `group:"server"` +// } +// +// func NewHelloHandler() HandlerResult { +// // ... +// } +// +// func NewEchoHandler() HandlerResult { +// // ... +// } +// +// Any number of constructors may provide values to this named collection, but +// the ordering of the final collection is unspecified. +// +// Value groups require parameter and result structs to use fields with +// different types: if a group of constructors each returns type T, parameter +// structs consuming the group must use a field of type []T. +// +// Parameter structs can request a value group by using a field of type []T +// tagged with `group:".."`. +// This will execute all constructors that provide a value to +// that group in an unspecified order, then collect all the results into a +// single slice. +// +// type ServerParams struct { +// fx.In +// +// Handlers []Handler `group:"server"` +// } +// +// func NewServer(p ServerParams) *Server { +// server := newServer() +// for _, h := range p.Handlers { +// server.Register(h) +// } +// return server +// } +// +// Note that values in a value group are unordered. Fx makes no guarantees +// about the order in which these values will be produced. +// +// # Soft Value Groups +// +// By default, when a constructor declares a dependency on a value group, +// all values provided to that value group are eagerly instantiated. +// That is undesirable for cases where an optional component wants to +// constribute to a value group, but only if it was actually used +// by the rest of the application. +// +// A soft value group can be thought of as a best-attempt at populating the +// group with values from constructors that have already run. In other words, +// if a constructor's output type is only consumed by a soft value group, +// it will not be run. +// +// Note that Fx randomizes the order of values in the value group, +// so the slice of values may not match the order in which constructors +// were run. +// +// To declare a soft relationship between a group and its constructors, use +// the `soft` option on the input group tag (`group:"[groupname],soft"`). +// This option is only valid for input parameters. +// +// type Params struct { +// fx.In +// +// Handlers []Handler `group:"server,soft"` +// Logger *zap.Logger +// } +// +// func NewServer(p Params) *Server { +// // ... +// } +// +// With such a declaration, a constructor that provides a value to the 'server' +// value group will be called only if there's another instantiated component +// that consumes the results of that constructor. +// +// func NewHandlerAndLogger() (Handler, *zap.Logger) { +// // ... +// } +// +// func NewHandler() Handler { +// // ... +// } +// +// fx.Provide( +// fx.Annotate(NewHandlerAndLogger, fx.ResultTags(`group:"server"`)), +// fx.Annotate(NewHandler, fx.ResultTags(`group:"server"`)), +// ) +// +// NewHandlerAndLogger will be called because the Logger is consumed by the +// application, but NewHandler will not be called because it's only consumed +// by the soft value group. +// +// # Value group flattening +// +// By default, values of type T produced to a value group are consumed as []T. +// +// type HandlerResult struct { +// fx.Out +// +// Handler Handler `group:"server"` +// } +// +// type ServerParams struct { +// fx.In +// +// Handlers []Handler `group:"server"` +// } +// +// This means that if the producer produces []T, +// the consumer must consume [][]T. +// +// There are cases where it's desirable +// for the producer (the fx.Out) to produce multiple values ([]T), +// and for the consumer (the fx.In) consume them as a single slice ([]T). +// Fx offers flattened value groups for this purpose. +// +// To provide multiple values for a group from a result struct, produce a +// slice and use the `,flatten` option on the group tag. This indicates that +// each element in the slice should be injected into the group individually. +// +// type HandlerResult struct { +// fx.Out +// +// Handler []Handler `group:"server,flatten"` +// // Consumed as []Handler in ServerParams. +// } +// +// # Unexported fields +// +// By default, a type that embeds fx.In may not have any unexported fields. The +// following will return an error if used with Fx. +// +// type Params struct { +// fx.In +// +// Logger *zap.Logger +// mu sync.Mutex +// } +// +// If you have need of unexported fields on such a type, you may opt-into +// ignoring unexported fields by adding the ignore-unexported struct tag to the +// fx.In. For example, +// +// type Params struct { +// fx.In `ignore-unexported:"true"` +// +// Logger *zap.Logger +// mu sync.Mutex +// } package fx // import "go.uber.org/fx" diff --git a/inout.go b/inout.go index 05303944c..e40ab8af6 100644 --- a/inout.go +++ b/inout.go @@ -22,343 +22,22 @@ package fx import "go.uber.org/dig" -// In can be embedded in a constructor's parameter struct to take advantage of -// advanced dependency injection features. -// -// Modules should take a single parameter struct that embeds an In in order to -// provide a forward-compatible API: since adding fields to a struct is -// backward-compatible, modules can then add optional dependencies in minor -// releases. -// -// # Parameter Structs -// -// Fx constructors declare their dependencies as function parameters. This can -// quickly become unreadable if the constructor has a lot of dependencies. -// -// func NewHandler(users *UserGateway, comments *CommentGateway, posts *PostGateway, votes *VoteGateway, authz *AuthZGateway) *Handler { -// // ... -// } -// -// To improve the readability of constructors like this, create a struct that -// lists all the dependencies as fields and change the function to accept that -// struct instead. The new struct is called a parameter struct. -// -// Fx has first class support for parameter structs: any struct embedding -// fx.In gets treated as a parameter struct, so the individual fields in the -// struct are supplied via dependency injection. Using a parameter struct, we -// can make the constructor above much more readable: -// -// type HandlerParams struct { -// fx.In -// -// Users *UserGateway -// Comments *CommentGateway -// Posts *PostGateway -// Votes *VoteGateway -// AuthZ *AuthZGateway -// } -// -// func NewHandler(p HandlerParams) *Handler { -// // ... -// } -// -// Though it's rarely a good idea, constructors can receive any combination of -// parameter structs and parameters. -// -// func NewHandler(p HandlerParams, l *log.Logger) *Handler { -// // ... -// } -// -// # Optional Dependencies -// -// Constructors often have optional dependencies on some types: if those types are -// missing, they can operate in a degraded state. Fx supports optional -// dependencies via the `optional:"true"` tag to fields on parameter structs. -// -// type UserGatewayParams struct { -// fx.In -// -// Conn *sql.DB -// Cache *redis.Client `optional:"true"` -// } -// -// If an optional field isn't available in the container, the constructor -// receives the field's zero value. -// -// func NewUserGateway(p UserGatewayParams, log *log.Logger) (*UserGateway, error) { -// if p.Cache == nil { -// log.Print("Caching disabled") -// } -// // ... -// } -// -// Constructors that declare optional dependencies MUST gracefully handle -// situations in which those dependencies are absent. -// -// The optional tag also allows adding new dependencies without breaking -// existing consumers of the constructor. -// -// # Named Values -// -// Some use cases require the application container to hold multiple values of -// the same type. For details on producing named values, see the documentation -// for the Out type. -// -// Fx allows functions to consume named values via the `name:".."` tag on -// parameter structs. Note that both the name AND type of the fields on the -// parameter struct must match the corresponding result struct. -// -// type GatewayParams struct { -// fx.In -// -// WriteToConn *sql.DB `name:"rw"` -// ReadFromConn *sql.DB `name:"ro"` -// } -// -// The name tag may be combined with the optional tag to declare the -// dependency optional. -// -// type GatewayParams struct { -// fx.In -// -// WriteToConn *sql.DB `name:"rw"` -// ReadFromConn *sql.DB `name:"ro" optional:"true"` -// } -// -// func NewCommentGateway(p GatewayParams, log *log.Logger) (*CommentGateway, error) { -// if p.ReadFromConn == nil { -// log.Print("Warning: Using RW connection for reads") -// p.ReadFromConn = p.WriteToConn -// } -// // ... -// } -// -// # Value Groups -// -// To make it easier to produce and consume many values of the same type, Fx -// supports named, unordered collections called value groups. For details on -// producing value groups, see the documentation for the Out type. -// -// Functions can depend on a value group by requesting a slice tagged with -// `group:".."`. This will execute all constructors that provide a value to -// that group in an unspecified order, then collect all the results into a -// single slice. Keep in mind that this makes the types of the parameter and -// result struct fields different: if a group of constructors each returns -// type T, parameter structs consuming the group must use a field of type []T. -// -// type ServerParams struct { -// fx.In -// -// Handlers []Handler `group:"server"` -// } -// -// func NewServer(p ServerParams) *Server { -// server := newServer() -// for _, h := range p.Handlers { -// server.Register(h) -// } -// return server -// } -// -// Note that values in a value group are unordered. Fx makes no guarantees -// about the order in which these values will be produced. -// -// # Soft Value Groups -// -// A soft value group can be thought of as a best-attempt at populating the -// group with values from constructors that have already run. In other words, -// if a constructor's output type is only consumed by a soft value group, -// it will not be run. -// -// Note that Fx does not guarantee precise execution order of constructors -// or invokers, which means that the change in code that affects execution -// ordering of other constructors or functions will affect the values -// populated in this group. -// -// To declare a soft relationship between a group and its constructors, use -// the `soft` option on the group tag (`group:"[groupname],soft"`). -// This option is only valid for input parameters. -// -// type Params struct { -// fx.In -// -// Handlers []Handler `group:"server,soft"` -// Logger *zap.Logger -// } -// -// NewHandlerAndLogger := func() (Handler, *zap.Logger) { ... } -// NewHandler := func() Handler { ... } -// Foo := func(Params) { ... } -// -// app := fx.New( -// fx.Provide(fx.Annotate(NewHandlerAndLogger, fx.ResultTags(`group:"server"`))), -// fx.Provide(fx.Annotate(NewHandler, fx.ResultTags(`group::"server"`))), -// fx.Invoke(Foo), -// ) -// -// The only constructor called is `NewHandlerAndLogger`, because this also provides -// `*zap.Logger` needed in the `Params` struct received by `Foo`. The Handlers -// group will be populated with a single Handler returned by `NewHandlerAndLogger`. -// -// In the next example, the slice `s` isn't populated as the provider would be -// called only because `strings` soft group value is its only consumer. -// -// app := fx.New( -// fx.Provide( -// fx.Annotate( -// func() (string, int) { return "hello", 42 }, -// fx.ResultTags(`group:"strings"`), -// ), -// ), -// fx.Invoke( -// fx.Annotate(func(s []string) { -// // s will be an empty slice -// }, fx.ParamTags(`group:"strings,soft"`)), -// ), -// ) -// -// In the next example, the slice `s` will be populated because there is a -// consumer for the same type which is not a `soft` dependency. -// -// app := fx.New( -// fx.Provide( -// fx.Annotate( -// func() string { "hello" }, -// fx.ResultTags(`group:"strings"`), -// ), -// ), -// fx.Invoke( -// fx.Annotate(func(b []string) { -// // b is []string{"hello"} -// }, fx.ParamTags(`group:"strings"`)), -// ), -// fx.Invoke( -// fx.Annotate(func(s []string) { -// // s is []string{"hello"} -// }, fx.ParamTags(`group:"strings,soft"`)), -// ), -// ) -// -// # Unexported fields -// -// By default, a type that embeds fx.In may not have any unexported fields. The -// following will return an error if used with Fx. -// -// type Params struct { -// fx.In -// -// Logger *zap.Logger -// mu sync.Mutex -// } -// -// If you have need of unexported fields on such a type, you may opt-into -// ignoring unexported fields by adding the ignore-unexported struct tag to the -// fx.In. For example, -// -// type Params struct { -// fx.In `ignore-unexported:"true"` -// -// Logger *zap.Logger -// mu sync.Mutex -// } +// In can be embedded into a struct to mark it as a parameter struct. +// This allows it to make use of advanced dependency injection features. +// See package documentation for more information. +// +// It's recommended that shared modules use a single parameter struct to +// provide a forward-compatible API: +// adding new optional fields to a struct is backward-compatible, +// so modules can evolve as needs change. type In = dig.In -// Out is the inverse of In: it can be embedded in result structs to take -// advantage of advanced features. -// -// Modules should return a single result struct that embeds an Out in order to -// provide a forward-compatible API: since adding fields to a struct is -// backward-compatible, minor releases can provide additional types. -// -// # Result Structs -// -// Result structs are the inverse of parameter structs (discussed in the In -// documentation). These structs represent multiple outputs from a -// single function as fields. Fx treats all structs embedding fx.Out as result -// structs, so other constructors can rely on the result struct's fields -// directly. -// -// Without result structs, we sometimes have function definitions like this: -// -// func SetupGateways(conn *sql.DB) (*UserGateway, *CommentGateway, *PostGateway, error) { -// // ... -// } -// -// With result structs, we can make this both more readable and easier to -// modify in the future: -// -// type Gateways struct { -// fx.Out -// -// Users *UserGateway -// Comments *CommentGateway -// Posts *PostGateway -// } -// -// func SetupGateways(conn *sql.DB) (Gateways, error) { -// // ... -// } -// -// # Named Values -// -// Some use cases require the application container to hold multiple values of -// the same type. For details on consuming named values, see the documentation -// for the In type. -// -// A constructor that produces a result struct can tag any field with -// `name:".."` to have the corresponding value added to the graph under the -// specified name. An application may contain at most one unnamed value of a -// given type, but may contain any number of named values of the same type. -// -// type ConnectionResult struct { -// fx.Out -// -// ReadWrite *sql.DB `name:"rw"` -// ReadOnly *sql.DB `name:"ro"` -// } -// -// func ConnectToDatabase(...) (ConnectionResult, error) { -// // ... -// return ConnectionResult{ReadWrite: rw, ReadOnly: ro}, nil -// } -// -// # Value Groups -// -// To make it easier to produce and consume many values of the same type, Fx -// supports named, unordered collections called value groups. For details on -// consuming value groups, see the documentation for the In type. -// -// Constructors can send values into value groups by returning a result struct -// tagged with `group:".."`. -// -// type HandlerResult struct { -// fx.Out -// -// Handler Handler `group:"server"` -// } -// -// func NewHelloHandler() HandlerResult { -// // ... -// } -// -// func NewEchoHandler() HandlerResult { -// // ... -// } -// -// Any number of constructors may provide values to this named collection, but -// the ordering of the final collection is unspecified. Keep in mind that -// value groups require parameter and result structs to use fields with -// different types: if a group of constructors each returns type T, parameter -// structs consuming the group must use a field of type []T. -// -// To provide multiple values for a group from a result struct, produce a -// slice and use the `,flatten` option on the group tag. This indicates that -// each element in the slice should be injected into the group individually. -// -// type IntResult struct { -// fx.Out -// -// Handler []int `group:"server"` // Consume as [][]int -// Handler []int `group:"server,flatten"` // Consume as []int -// } +// Out is the inverse of In: it marks a struct as a result struct so that +// it can be used with advanced dependency injection features. +// See package documentation for more information. +// +// It's recommended that shared modules use a single result struct to +// provide a forward-compatible API: +// adding new fields to a struct is backward-compatible, +// so modules can produce more outputs as they grow. type Out = dig.Out