github.com/aacfactory/fns@v1.2.86-0.20240310083819-80d667fc0a17/docs/definition.md (about)

     1  # Definition
     2  
     3  ------
     4  
     5  ## Service
     6  
     7  Service is a group of `fn`. and it is core unit, everything are service, such as database and message queues, annotations of service are:
     8  
     9  | Annotation  | Type   | Required | Description                                                                        |
    10  |-------------|--------|----------|------------------------------------------------------------------------------------|
    11  | service     | string | true     | name of service                                                                    |
    12  | title       | string | false    | used for tag name of oas                                                           |
    13  | description | string | false    | used for tag description of oas                                                    |
    14  | internal    | bool   | false    | it value is true, then fn in this service cannot be accessed by the public network |
    15  
    16  
    17  
    18  ## Fn
    19  
    20  Fn is a business function, the first argument type must be a `context.Context` and the second argument type must be a `struct`, the first return value type must be a `pointer` or `slice`, the second return value type must be `errors.CodeError`, annotations of fn are:
    21  
    22  | Annotation    | Type                               | Required | Description                                                                        |
    23  |---------------|------------------------------------|----------|------------------------------------------------------------------------------------|
    24  | fn            | string                             | true     | name of fn                                                                         |
    25  | validate      | bool                               | false    | whether parameter verification is required                                         |
    26  | authorization | bool                               | false    | whether authorization verification is required                                     |
    27  | permission    | []roleName                         | false    | whether permission verification is required and what roles can access the fn       |
    28  | transactional | enum(sql, postgres, mysql, dgraph) | false    | whether to start database transaction                                              |
    29  | deprecated    | bool                               | false    | deprecated                                                                         |
    30  | title         | string                             | false    | used for request title of oas                                                      |
    31  | description   | string                             | false    | used for request description of oas                                                |
    32  | internal      | bool                               | false    | it value is true, then fn in this service cannot be accessed by the public network |
    33  
    34  ## Context
    35  The context of request is a tree, the context of each function is on the request context tree.
    36  
    37  ```text
    38  |-- request context
    39      |-- fn context
    40      |-- fn context
    41          |-- fn context
    42  ```
    43  There are `current fn log`, `current service components`, `application id`, `service endpoint discovery` and `tracer` in the context.
    44  
    45  For example:
    46  ```go
    47  log := service.GetLog(ctx)
    48  
    49  ```
    50  
    51  ## Argument field tag
    52  
    53  | Tag      | Type   | Required | Description                                                                          |
    54  |----------|--------|----------|--------------------------------------------------------------------------------------|
    55  | json     | string | false    | json tag                                                                             |
    56  | validate | string | false    | validator name, implement by [validator](https://github.com/go-playground/validator) |
    57  | message  | string | false    | validate failed message                                                              |
    58  
    59  ## Task
    60  The task is a goroutine proxy, and it is managed by fns goroutine pool.