README
¶
nirvana
Introduction
nirvana is a golang http framework designed with productivity and usability in mind. It aims to be the building block for all golang services in Caicloud. The high-level goals are:
- Reduce api level errors and inconsistency
- Improve engineering productivity via removing repeated work, adding code generation, etc
- Adding new resource type should only require defining struct definition
- Adding validation should only require declaring validation method as part of struct definition
- Consistent behavior, structure and layout across all golang server projects
Features
Following is a list of requirements we've seen from writing golang services. Some of these features are general ones while some are specific to Caicloud. Note this is not an exhaustive list.
Routing, Request & Response
- Routes mapping from request to function
- Routes grouping
- Request/Response API object marshal/unmarshal
- General middleware support with sane default (logging, recovery, tracing)
- Contextual process chain and parameter injection
- Enforcing API error convention
Instrumentation
- Provide default metrics at well-known endpoints for prometheus to scrape
- Tracing is provided by default to allow better troubleshooting
- Profiling can be enabled in debug mode for troubleshootting
Validation
- Provide default validation on api types with struct tags
- Support custom validations defined by developers on api types
- Support validation on all parameters (path, query, etc)
Usability
- A working project should be brought up with few lines using the framework
- Framework must automatically follow engineering conventions to help developers focus on business logic
- OpenAPI (swagger 2.0) specification can be generated automatically with no extra work
- Provides a well-established layout conforming to golang project layout
- Easy and standard configuration management
- A reasonable support for websocket
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterConfigInstaller ¶
func RegisterConfigInstaller(ci ConfigInstaller)
RegisterConfigInstaller registers a config installer.
Types ¶
type Config ¶
type Config struct {
// IP is the ip to listen. Empty means `0.0.0.0`.
IP string
// Port is the port to listen.
Port uint16
// Logger is used to output info inside framework.
Logger log.Logger
// Descriptors contains all APIs.
Descriptors []definition.Descriptor
// Filters is http filters.
Filters []service.Filter
// Modifiers is definition modifiers
Modifiers service.DefinitionModifiers
// contains filtered or unexported fields
}
Config describes configuration of server.
func NewDefaultConfig ¶
NewDefaultConfig creates default config. Default config contains:
Filters: RedirectTrailingSlash, FillLeadingSlash, ParseRequestForm.
Modifiers: FirstContextParameter, EmptyConsumeForHTTPGet,
ConsumeAllIfComsumesIsEmpty, ProduceAllIfProducesIsEmpty,
ConsumeNoneForHTTPGet, ConsumeNoneForHTTPDelete,
ProduceNoneForHTTPDelete.
func (*Config) Configure ¶
func (c *Config) Configure(configurers ...Configurer) *Config
Configure configs by configurers. It panics if an error occurs.
type ConfigInstaller ¶
type ConfigInstaller interface {
// Name is the external config name.
Name() string
// Install installs stuffs before server starting.
Install(builder service.Builder, config *Config) error
// Uninstall uninstalls stuffs after server terminating.
Uninstall(builder service.Builder, config *Config) error
}
ConfigInstaller is used to install config to service builder.
func ConfigInstallerFor ¶
func ConfigInstallerFor(name string) ConfigInstaller
ConfigInstallerFor gets installer by name.
type Configurer ¶
Configurer is used to configure server config.
func Descriptor ¶
func Descriptor(descriptors ...definition.Descriptor) Configurer
Descriptor returns a configurer to add descriptors into config.
func Filter ¶
func Filter(filters ...service.Filter) Configurer
Filter returns a configurer to add filters into config.
func Logger ¶
func Logger(logger log.Logger) Configurer
Logger returns a configurer to set logger into config.
func Modifier ¶
func Modifier(modifiers ...service.DefinitionModifier) Configurer
Modifier returns a configurer to add definition modifiers into config.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
openapi-gen
command
|
|
|
examples
|
|
|
api-basic
command
|
|
|
cli
command
|
|
|
instrumentation
command
|
|
|
openapi
command
|
|
|
openapi/pkg/api/v1
Package v1 is definition of api +caicloud:openapi=true
|
Package v1 is definition of api +caicloud:openapi=true |
|
stream
command
|
|
|
swapi/cmd/swapi
command
|
|
|
tracing
command
|
|
|
hack
|
|
|
flag-gen
command
|
|
|
license
command
|
|
|
operators
|
|
|
plugins
|
|
|
utils
|
|