slimapi

Documentation

Overview

Package slimapi 基于 webapi 包，实现基于 SlimAPI 协议的开发框架。

SlimAPI 是一个基于 HTTP WebAPI 的通信契约。旨在将代码与 HTTP 通信解耦，使编码者可以更多的关注业务逻辑而不是通信方式。

SlimAPI 请求

可以通过 HTTP 的 Content-Type 头指定使用何种格式请求，目前支持的类型如下：

• GET 不读取 Content-Type 头。
• POST FORM 表单格式， Content-Type 可以是 application/x-www-form-urlencoded 或 multipart/form-data 。
• POST JSON 以 JSON 作为数据，值为 application/json 。

也可以不指定 Content-Type 头，而通过`~format`参数指定格式，详见下文。

URL 形式1

http://domain/ApiEntry?~method=METHOD&~format=FORMAT&~callback=CALLBACK

以“~”标记的参数为 API 框架的元参数：

• ~method：必填；表示被调用的方法的名称。
• ~format：可选；请求所使用的数据格式，支持get/post/json；此参数在可以在不方面指定`Content-Type`时提供相同的功能。
• ~callback：可选；JSONP回调函数的名称，一旦制定此参数，返回一个 JSONP 结果，Content-Type: text/javascript 。

参数名称都是大小写不敏感的。`~format`参数优先级高于`Content-Type`，若指定了`~format`，则`Content-Type`的值被忽略。

`~format`的可选值：

• get 默认值。使用 GET 方式处理。
• post 效果等同于给定 Content-Type: application/x-www-form-urlencoded
• json 效果等同于给定 Content-Type: application/json

URL 形式2

http://domain/ApiEntry?METHOD.FORMAT(CALLBACK) 不需要再写参数名字，直接将需要的元参数值追加在URL后面。

同形式1，“.FORMAT”和“(CALLBACK)”是可选的， 省略“.FORMAT”后形如： http://domain/ApiEntry?METHOD(CALLBACK) ； 省略“(CALLBACK)”后形如： http://domain/ApiEntry?METHOD.FORMAT 。

URL 形式3

通过路由规则，将元参数编排到 URL 路径里。这是最常见的方案： http://domain/ApiEntry/METHOD 这里 METHOD 就是元参数 ~method 。

SlimAPI 请求参数的格式

请求参数

• GET 参数体现在 URL 上，形如 data=1&name=abc&time=2014-4-8 。
• 表单 以 POST 方式放在HTTP BODY中。
• JSON 只能使用 POST 方式上送。

可在 GET/表单参数中传递简单的数组，数组元素间使用 ~ 分割，如 1~2~3~4~5 可表示数组 [1, 2, 3, 4, 5]。

在GET/表单格式下：

data=1&name=abc&time=2014-4-8&array=1~2~3~4

与JSON格式下的下面内容等价：

{ "data":1, "name": "abc", "time": "2014-4-8", "array": [1, 2, 3, 4] }

日期格式使用字符串的 yyyy-MM-dd HH:mm:ss 格式，默认为 UTC 时间。也支持 RFC3339 ，这种格式自带时区。

SlimAPI 回执格式

若指定了 ~callback 参数，则返回结果为 JSONP 格式： Content-Type: text/javascript ；否则为 JSON 格式： Content-Type: application/json 。

状态码总是200，具体异常码需要从Code字段判定。数据装在一个基本的信封中，信封格式如下：

{ Code: 0, Message: "", Data: {} }

- Code 0为API调用成功未见异常，非0值为异常：
	- 1-999 API请求、通信及运行时异常，尽可能与 HTTP 状态码一致：
		- 500 服务端内部异常。
		- 400 请求参数或报文错误。
		- 403 客户端无访问权限。
	- 其他约定：
	- -1 未明确定义的错误。
	- 1000-9999 预留
	- 大于等于10000为业务预定义异常，由具体API自行定义，但建议至少分为用户可见和不可见两个区间：
		- 10000-19999 建议保留为不提示给用户的业务异常，对接 API 的客户端对于这些异常码，对用户提示一个统一的如“网络异常”的错误。
		- 20000-29999 对接 API 的客户端可直接将 Message 展示给用户，用于展示的错误消息需要由服务端控制的场景。
- Message 附加信息， Code 不为0时记录错误描述，可为空字符串。
- Data 返回的主数据，不同API各不相同，其所有可能形式如下：
	- 若API没有返回值，则为 null 。
	- 对于返回布尔型结果的 API ，Data 为 true 或 false 。
	- 对于返回数值结果的 API ，Data即为数值，如：123.654 。
	- 对于返回字符串结果的 API ， Data 为字符串，如："string value" 。
	- 日期也作为字符串，参照前面提到的日期格式。
	- 对于返回集合的 API ， Data 为数组，如： ["result1", "result2"] 。
	- 对于返回复杂对象的 API ，Data 为 JSON object ，如：{ "Field1": "Value1", "Field2": "Value2" } 。

Index

• Constants
• Variables
• func NewSlimApiDecoder() webapi.ArgumentDecoderPipeline
• func NewSlimApiHandler(name string) *webapi.ApiHandlerWrapper
• func NewSlimApiLogger() webapi.LogSetupPipeline
• func NewSlimApiNameResolver() webapi.ApiNameResolver
• func NewSlimApiResponseWriter() webapi.ApiResponseWriter
• func ParseTime(v string) (time.Time, error)
• func SupportedHttpMethods() []string
• type SlimApiInvoker
  • func NewSlimApiInvoker[TParam, TData any](uri string) *SlimApiInvoker[TParam, TData]
  • func (x SlimApiInvoker[TParam, TData]) Do(params TParam) (data TData, err error)
  • func (x SlimApiInvoker[TParam, TData]) DoRaw(params TParam) (res webapi.ApiResponse[TData], err error)
  • func (x SlimApiInvoker[TParam, TData]) MustDo(params TParam) TData
  • func (x SlimApiInvoker[TParam, TData]) MustDoRaw(params TParam) webapi.ApiResponse[TData]
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t Time) String() string
  • func (t Time) Time() time.Time

Constants

const (
	// SlimAPI 协议里默认的时间格式： yyyy-MM-dd HH:mm:ss 。 API 输出 JSON 时使用此格式。
	TimeFormat = "2006-01-02 15:04:05"
)

Variables

var Conv = conv.Conv{
	Conf: conv.Config{
		FieldMatcherCreator: &conv.SimpleMatcherCreator{
			Conf: conv.SimpleMatcherConfig{
				CaseInsensitive: true,
			},
		},
		StringToTime:   ParseTime,
		StringSplitter: func(v string) []string { return strings.Split(v, "~") },
	},
}

Conv 是用于 SlimAPI 的 conv.Conv 实例，它支持：

• 使用大小写不敏感（case-insensitive）的方式处理字段。
• 支持 SlimAPI 规定的时间格式 yyyyMMdd HH:mm:ss 。
• 支持字符串到数组的转换，使用 ~ 分割，如将 "1~2~3" 转为 [1, 2, 3] 。

var LogBody = logBody{}

LogBody 实现 webapi.LogSetup ，用于记录请求的 body 的相关信息。

这是一个单例。

var StructArgumentDecoder = slimApiMethodStructArgDecoder{}

StructArgumentDecoder 是一个 webapi.ArgumentDecoder ， 定义了 SlimAPI 协议的参数解析过程，用于方法参数表中 struct 类型的参数。

这是一个单例。

Functions

func NewSlimApiDecoder

func NewSlimApiDecoder() webapi.ArgumentDecoderPipeline

NewSlimApiDecoder 返回用于 SlimAPI 协议的 webapi.ApiDecoder 实现。

func NewSlimApiHandler

func NewSlimApiHandler(name string) *webapi.ApiHandlerWrapper

NewSlimApiHandler 创建一个实现 SlimAPI 协议的 webapi.ApiHandlerWrapper 。 可通过替换其成员实现接口的定制。

func NewSlimApiLogger

func NewSlimApiLogger() webapi.LogSetupPipeline

NewSlimApiLogger 返回用于 SlimAPI 协议的 webapi.ApiLogger 实现。

func NewSlimApiNameResolver

func NewSlimApiNameResolver() webapi.ApiNameResolver

NewSlimApiNameResolver 返回用于 SlimAPI 协议的 webapi.ApiNameResolver 实现。

func NewSlimApiResponseWriter

func NewSlimApiResponseWriter() webapi.ApiResponseWriter

NewSlimApiResponseWriter 返回用于 SlimAPI 协议的 webapi.ApiResponseWriter 实现。 该实现是无状态且线程安全的。

func ParseTime

func ParseTime(v string) (time.Time, error)

ParseTime 解析 SlimAPI 的时间格式，默认 yyyyMMdd HH:mm:ss 时区为 UTC ，如果解析失败再用默认的格式（ RFC3339 ）处理。

func SupportedHttpMethods

func SupportedHttpMethods() []string

SupportedHttpMethods 返回 SlimAPI 支持的 HTTP 请求方法。 当前支持 GET 和 POST 。

Types

type SlimApiInvoker

type SlimApiInvoker[TParam, TData any] struct {
	// 目标 URL 。
	Uri string

	// 若不为 nil ，则在 [http.Client.Do] 之前，调用此函数对当前请求进行处理。
	RequestSetup func(r *http.Request) error
}

SlimApiInvoker 用于调用一个 SlimAPI 。

TParam 是输入参数的类型； TData 对应输出的 webapi.ApiResponse.Data 。

func NewSlimApiInvoker

func NewSlimApiInvoker[TParam, TData any](uri string) *SlimApiInvoker[TParam, TData]

SlimApiInvoker 创建一个 SlimApiInvoker 实例。

func (SlimApiInvoker[TParam, TData]) Do

func (x SlimApiInvoker[TParam, TData]) Do(params TParam) (data TData, err error)

Do 执行请求并在 webapi.ApiResponse.Code 为 0 时返回 webapi.ApiResponse.Data 。 若 Code 不是 0 ，则返回 errx.BizError 。

func (SlimApiInvoker[TParam, TData]) DoRaw

func (x SlimApiInvoker[TParam, TData]) DoRaw(params TParam) (res webapi.ApiResponse[TData], err error)

DoRaw 执行请求，并返回原始的 webapi.ApiResponse ，不会判断对应的 Code 值。

请求总是以 Content-Type: application/json 方式发送， params 是请求的参数，需能够被 JSON 序列化。

func (SlimApiInvoker[TParam, TData]) MustDo

func (x SlimApiInvoker[TParam, TData]) MustDo(params TParam) TData

MustDo 是 [Do] 的 panic 版本。

func (SlimApiInvoker[TParam, TData]) MustDoRaw

func (x SlimApiInvoker[TParam, TData]) MustDoRaw(params TParam) webapi.ApiResponse[TData]

MustDoRaw 是 [DoRaw] 的 panic 版本。

type Time

type Time time.Time

Time 描述 SlimAPI 协议中的时间。

在 API response 中，使用此类型，可输出 SlimAPI 格式的时间。 e.g.

type SomeResponse struct {
    CreateTime time.Time    // 在 JSON 中使用默认的格式（RFC3339）输出。
    UpdateTime slimapi.Time // 在 JSON 中使用 SlimAPI 规定的格式输出： yyyy-MM-dd HH:mm:ss 。
}

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

Implements json.Marshaler.

func (Time) String

func (t Time) String() string

Implements fmt.Stringer.

func (Time) Time

func (t Time) Time() time.Time

Time 将 slimapi.Time 转换到标准库的 time.Time 。