server

Documentation

Overview

Package server 提供与服务端实现相关的功能

目前实现了三种类型的服务端：

• NewHTTP 构建普通的 HTTP 服务；
• NewGateway 构建微服务的网关服务；
• NewService 构建微服务；

Index

• Constants
• func NewGateway(name, version string, o *Options) (web.Server, error)
• func NewHTTP(name, version string, o *Options) (web.Server, error)
• func NewService(name, version string, o *Options) (web.Server, error)
• func Render200(status int, body any) (int, any)
• type Options
• type RenderResponse
  • func (r *RenderResponse) MarshalHTML() (string, any)

Constants

const DefaultConfigDir = "@.config" // 默认的配置目录地址

Functions

func NewGateway

func NewGateway(name, version string, o *Options) (web.Server, error)

NewGateway 声明微服务的网关

[Options.Mapper] 和 [Options.Peer] 不能为空。

func NewHTTP

func NewHTTP(name, version string, o *Options) (web.Server, error)

NewHTTP 新建 HTTP 服务

name, version 表示服务的名称和版本号； o 指定了一些带有默认值的参数；

func NewService

func NewService(name, version string, o *Options) (web.Server, error)

NewService 声明微服务节点

[Options.Registry] 和 [Options.Peer] 不能为空。

func Render200

func Render200(status int, body any) (int, any)

Render200 统一 API 的返回格式

适用 [Options.OnRender]。

返回值中，状态码统一为 http.StatusOK。返回对象统一为 RenderResponse。

Types

type Options

type Options struct {
	// 项目的配置文件管理
	//
	// 如果为空，则采用 [DefaultConfigDir] 作为配置文件的目录，
	// 同时加载 YAML、XML 和 JSON 三种文件类型的序列化方法。
	Config *config.Config

	// 服务器的时区
	//
	// 默认值为 [time.Local]
	Location *time.Location

	// 缓存系统
	//
	// 如果为空，采用 [github.com/issue9/cache/caches/memory/New] 作为默认值。
	Cache cache.Driver

	// 日志系统
	//
	// 如果此值为空，表示不会输出任何信息。
	//
	// 会调用 [logs.Logs.SetLocale] 设置为 [Language] 的值。
	Logs *logs.Logs

	// http.Server 实例的值
	HTTPServer *http.Server

	// 生成唯一字符串的方法
	//
	// 供 [Server.UniqueID] 使用。
	//
	// 如果为空，将采用 [unique.NewString] 作为生成方法。
	//
	// NOTE: 该值的修改，可能造成项目中的唯一 ID 不再唯一。
	IDGenerator func() string

	// 路由选项
	RoutersOptions []web.RouterOption

	// 指定获取 x-request-id 内容的报头名
	//
	// 如果为空，则采用 [header.XRequestID] 作为默认值
	RequestIDKey string

	// 编码方式
	//
	// 如果为空，则仅支持 JSON 编码，不支持压缩方式。
	Codec *web.Codec

	// 默认的语言标签
	//
	// 在用户请求的报头中没有匹配的语言标签时，会采用此值作为该用户的本地化语言，
	// 同时也用来初始化 [Server.Locale.Printer]。
	//
	// 框架中的日志输出时，如果该信息实现了 [web.LocaleStringer] 接口，
	// 将会转换成此设置项的语言。
	//
	// 如果为空，即 [language.Und]，则会尝试读取当前系统的本地化信息。
	Language language.Tag

	// 所有 [web.Problem.Type] 字段的前缀
	//
	// 如果该值为 [web.ProblemAboutBlank]，将不输出 ID 值；其它值则作为前缀添加。
	// 空值是合法的值，表示不需要添加前缀。
	ProblemTypePrefix string

	// OnRender 可实现对渲染结果的调整
	//
	// 默认为空。
	//
	// NOTE: 该值的修改，可能造成所有接口返回数据结构的变化。
	OnRender func(status int, body any) (int, any)

	// 指定对 [web.Server] 进行初始化的插件
	//
	// 这些插件会在 [web.Server.Serve] 运行之前被调用。
	Plugins []web.Plugin

	// 作为微服务时的注册中心实例
	//
	// NOTE: 仅在 [NewService] 和 [NewGateway] 中才会有效果。
	Registry registry.Registry

	// 作为微服务终端时的地址
	//
	// NOTE: 仅在 [NewService] 中才会有效果。
	Peer selector.Peer

	// 作为微服务网关时的 URL 映射关系
	//
	// NOTE: 仅在 [NewGateway] 中才会有效果。
	Mapper map[string]web.RouterMatcher
	// contains filtered or unexported fields
}

Options 初始化 web.Server 的参数

NOTE: 这些参数都有默认值，且无法在 web.Server 初始化之后进行更改。

type RenderResponse

type RenderResponse struct {
	XMLName struct{} `json:"-" yaml:"-" xml:"body" cbor:"-"`
	OK      bool     `json:"ok" yaml:"ok" xml:"ok,attr" cbor:"ok"`                 // 是否是错误代码
	Status  int      `json:"status" yaml:"status" xml:"status,attr" cbor:"status"` // 原始的状态码
	Body    any      `json:"body" yaml:"body" xml:"body" cbor:"body"`
}

RenderResponse API 统一的返回格式

func (*RenderResponse) MarshalHTML

func (r *RenderResponse) MarshalHTML() (string, any)