definition 包

definition 包包含了 Nirvana 的 API 定义，用于描述 API 的参数与返回值。

  1. // Chain contains all subsequent actions.
  2. type Chain interface {
  3.     // Continue continues to execute the next subsequent actions.
  4.     Continue(context.Context) error
  5. }
  7. // Middleware describes the form of middlewares. If you want to
  8. // carry on, call Chain.Continue() and pass the context.
  9. type Middleware func(context.Context, Chain) error
  11. // Operator is used to operate an object and return an replacement object.
  12. //
  13. // For example:
  14. //  A converter:
  15. //    type ConverterForAnObject struct{}
  16. //    func (c *ConverterForAnObject) Kind() {return "converter"}
  17. //    func (c *ConverterForAnObject) In() reflect.Type {return definition.TypeOf(&ObjectV1{})}
  18. //    func (c *ConverterForAnObject) Out() reflect.Type {return definition.TypeOf(&ObjectV2{})}
  19. //    func (c *ConverterForAnObject) Operate(ctx context.Context, object interface{}) (interface{}, error) {
  20. //        objV2, err := convertObjectV1ToObjectV2(object.(*ObjectV1))
  21. //        return objV2, err
  22. //    }
  23. //
  24. //  A validator:
  25. //    type ValidatorForAnObject struct{}
  26. //    func (c *ValidatorForAnObject) Kind() {return "validator"}
  27. //    func (c *ValidatorForAnObject) In() reflect.Type {return definition.TypeOf(&Object{})}
  28. //    func (c *ValidatorForAnObject) Out() reflect.Type {return definition.TypeOf(&Object{})}
  29. //    func (c *ValidatorForAnObject) Operate(ctx context.Context, object interface{}) (interface{}, error) {
  30. //        if err := validate(object.(*Object)); err != nil {
  31. //            return nil, err
  32. //        }
  33. //        return object, nil
  34. //    }
  35. type Operator interface {
  36.     // Kind indicates operator type.
  37.     Kind() string
  38.     // In returns the type of the only object parameter of operator.
  39.     // The type must be a concrete struct or built-in type. It should
  40.     // not be interface unless it's a file or stream reader.
  41.     In() reflect.Type
  42.     // Out returns the type of the only object result of operator.
  43.     // The type must be a concrete struct or built-in type. It should
  44.     // not be interface unless it's a file or stream reader.
  45.     Out() reflect.Type
  46.     // Operate operates an object and return one.
  47.     Operate(ctx context.Context, field string, object interface{}) (interface{}, error)
  48. }
  50. // Method is an alternative of HTTP method. It's more clearer than HTTP method.
  51. // A definition method binds a certain HTTP method and a success status code.
  52. type Method string
  54. const (
  55.     // List binds to http.MethodGet and code http.StatusOK(200).
  56.     List Method = "List"
  57.     // Get binds to http.MethodGet and code http.StatusOK(200).
  58.     Get Method = "Get"
  59.     // Create binds to http.MethodPost and code http.StatusCreated(201).
  60.     Create Method = "Create"
  61.     // Update binds to http.MethodPut and code http.StatusOK(200).
  62.     Update Method = "Update"
  63.     // Patch binds to http.MethodPatch and code http.StatusOK(200).
  64.     Patch Method = "Patch"
  65.     // Delete binds to http.MethodDelete and code http.StatusNoContent(204).
  66.     Delete Method = "Delete"
  67.     // AsyncCreate binds to http.MethodPost and code http.StatusAccepted(202).
  68.     AsyncCreate Method = "AsyncCreate"
  69.     // AsyncUpdate binds to http.MethodPut and code http.StatusAccepted(202).
  70.     AsyncUpdate Method = "AsyncUpdate"
  71.     // AsyncPatch binds to http.MethodPatch and code http.StatusAccepted(202).
  72.     AsyncPatch Method = "AsyncPatch"
  73.     // AsyncDelete binds to http.MethodDelete and code http.StatusAccepted(202).
  74.     AsyncDelete Method = "AsyncDelete"
  75. )
  77. // Source indicates which place a value is from.
  78. type Source string
  80. const (
  81.     // Path means value is from URL path.
  82.     Path Source = "Path"
  83.     // Query means value is from URL query string.
  84.     Query Source = "Query"
  85.     // Header means value is from request header.
  86.     Header Source = "Header"
  87.     // Form means value is from request body and content type must be
  88.     // "application/x-www-form-urlencoded" and "multipart/form-data".
  89.     Form Source = "Form"
  90.     // File means value is from request body and content type must be
  91.     // "multipart/form-data".
  92.     File Source = "File"
  93.     // Body means value is from request body.
  94.     Body Source = "Body"
  95.     // Auto identifies a struct and generate field values by field tag.
  96.     //
  97.     // Tag name is "source". Its value format is "Source,Name".
  98.     //
  99.     // ex.
  100.     // type Example struct {
  101.     //     Start       int    `source:"Query,start"`
  102.     //     ContentType string `source:"Header,Content-Type"`
  103.     // }
  104.     Auto Source = "Auto"
  105.     // Prefab means value is from a prefab generator.
  106.     // A prefab combines data to generate value.
  107.     Prefab Source = "Prefab"
  108. )
  110. // Destination indicates the target type to place function results.
  111. type Destination string
  113. const (
  114.     // Meta means result will be set into the header of response.
  115.     Meta Destination = "Meta"
  116.     // Data means result will be set into the body of response.
  117.     Data Destination = "Data"
  118.     // Error means the result is an error and should be treated specially.
  119.     // An error occurs indicates that there is no data to return. So the
  120.     // error should be treated as data and be writed back to client.
  121.     Error Destination = "Error"
  122. )
  124. // Example is just an example.
  125. type Example struct {
  126.     // Description describes the example.
  127.     Description string
  128.     // Instance is a custom data.
  129.     Instance interface{}
  130. }
  132. // Parameter describes a function parameter.
  133. type Parameter struct {
  134.     // Source is the parameter value generated from.
  135.     Source Source
  136.     // Name is the name to get value from a request.
  137.     // ex. a query name, a header key, etc.
  138.     Name string
  139.     // Default value is used when a request does not provide a value
  140.     // for the parameter.
  141.     Default interface{}
  142.     // Operators can modify and validate the target value.
  143.     // Parameter value is passed to the first operator, then
  144.     // previous operator's result is as next operator's parameter.
  145.     // The result of last operator will be passed to target function.
  146.     Operators []Operator
  147.     // Description describes the parameter.
  148.     Description string
  149. }
  151. // Result describes how to handle a result from function results.
  152. type Result struct {
  153.     // Destination is the target for the result. Different types make different behavior.
  154.     Destination Destination
  155.     // Operators can modify the result value.
  156.     // Result value is passed to the first operator, then
  157.     // previous operator's result is as next operator's parameter.
  158.     // The result of last operator will be passed to destination handler.
  159.     Operators []Operator
  160.     // Description describes the result.
  161.     Description string
  162. }
  164. // Definition defines an API handler.
  165. type Definition struct {
  166.     // Method is definition method.
  167.     Method Method
  168.     // Consumes indicates how many content types the handler can consume.
  169.     // It will override parent descriptor's consumes.
  170.     Consumes []string
  171.     // Produces indicates how many content types the handler can produce.
  172.     // It will override parent descriptor's produces.
  173.     Produces []string
  174.     // ErrorProduces is used to generate data for error. If this field is empty,
  175.     // it means that this field equals to Produces.
  176.     // In some cases, succeessful data and error data should be generated in
  177.     // different ways.
  178.     ErrorProduces []string
  179.     // Function is a function handler. It must be func type.
  180.     Function interface{}
  181.     // Parameters describes function parameters.
  182.     Parameters []Parameter
  183.     // Results describes function retrun values.
  184.     Results []Result
  185.     // Summary is a one-line brief description of this definition.
  186.     Summary string
  187.     // Description describes the API handler.
  188.     Description string
  189.     // Examples contains many examples for the API handler.
  190.     Examples []Example
  191. }
  193. // Descriptor describes a descriptor for API definitions.
  194. type Descriptor struct {
  195.     // Path is the url path. It will inherit parent's path.
  196.     //
  197.     // If parent path is "/api/v1", current is "/some",
  198.     // It means current definitions handles "/api/v1/some".
  199.     Path string
  200.     // Consumes indicates content types that current definitions
  201.     // and child definitions can consume.
  202.     // It will override parent descriptor's consumes.
  203.     Consumes []string
  204.     // Produces indicates content types that current definitions
  205.     // and child definitions can produce.
  206.     // It will override parent descriptor's produces.
  207.     Produces []string
  208.     // Middlewares contains path middlewares.
  209.     Middlewares []Middleware
  210.     // Definitions contains definitions for current path.
  211.     Definitions []Definition
  212.     // Children is used to place sub-descriptors.
  213.     Children []Descriptor
  214.     // Description describes the usage of the path.
  215.     Description string
  216. }

Descriptor 结构体包含具有如下含义的字段：

  1. API 路径
  2. 可被 Middlewares，Definitions，Children 继承的字段
  3. 其他与 API 路径同等级别的字段

如果希望对 Descriptor 进行扩展，需要遵守上面这些规则。

Definition 结构体包含了一个具体的 API 定义：

  1. API 方法，这个方法是一个抽象方法，用于描述一种行为（比如 Create）。
  2. API 参数和返回值定义
  3. 其他与具体 API 同等级别的字段

如果希望对 Definition 进行扩展，需要遵守上面这些规则。

Parameter 和 Result 分别对应 API 的参数和返回值，与业务函数的参数与返回值一一对应。字段定义与参数和返回值的转换有关。

在上面的定义中，存在两个额外功能：

  1. 在 Descriptor 中提供了 Middleware
  2. 在 Parameter 和 Result 中，提供了 Operator

其中 Middleware 提供了中间件的能力，可以在请求之前让用户对请求进行一些特殊处理。而 Operator 则针对单个的业务参数和返回值，可以对值进行验证和修改。

definition 包除了包含对 API 的定义以外，还提供了一些函数，帮助快速构建 Definitions 和 Operators：

  1. // MIME types
  2. const (
  3.     // acceptTypeAll indicates a accept type from http request.
  4.     // It means client can receive any content.
  5.     // Request content type in header "Content-Type" must not set to "*/*".
  6.     // It only can exist in request header "Accept".
  7.     // In most time, it locate at the last element of "Accept".
  8.     // It's default value if client have not set "Accept" header.
  9.     MIMEAll         = "*/*"
  10.     MIMENone        = ""
  11.     MIMEText        = "text/plain"
  12.     MIMEJSON        = "application/json"
  13.     MIMEXML         = "application/xml"
  14.     MIMEOctetStream = "application/octet-stream"
  15.     MIMEURLEncoded  = "application/x-www-form-urlencoded"
  16.     MIMEFormData    = "multipart/form-data"
  17. )
  19. // OperatorFunc creates operator by function.
  20. // function must has signature:
  21. //  func f(context.Context, string, AnyType) (AnyType, error)
  22. // The second parameter is a string that is used to identify field.
  23. // AnyType can be any type in go. But struct type and
  24. // built-in data type is recommended.
  25. func OperatorFunc(kind string, f interface{}) Operator