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

     1  # Usage
     2  
     3  ---
     4  
     5  ## Create service
     6  1. Create service pkg under `modules`
     7  2. Create `doc.go` under service pkg
     8  
     9  Example:
    10  ```go
    11  // Package users
    12  // @service users
    13  // @title Users
    14  // @description User service
    15  // @internal false
    16  package users
    17  ```
    18  
    19  ## Create service components when required
    20  
    21  Create `components` dir under created service dir,
    22  then create `component` which is implement `services.Component`.  
    23  Components are not required in most cases, unless the service needs to integrate third-party services.
    24  
    25  Structure of component:
    26  
    27  ```text
    28  |-- {service dir}
    29      |-- components
    30          |-- component.go
    31  ```
    32  
    33  component.go
    34  
    35  ```go
    36  // HelloComponent
    37  // @component
    38  type HelloComponent struct {
    39  }
    40  
    41  func (component *HelloComponent) Name() (name string) {
    42      return "hello"
    43  }
    44  
    45  func (component *HelloComponent) Construct(options services.Options) (err error) {
    46      return
    47  }
    48  
    49  func (component *HelloComponent) Shutdown(ctx context.Context) {
    50  }
    51  
    52  ```
    53  
    54  ## Create fn
    55  
    56  Create go file under created service dir, then create a private go func.
    57  Finally use `fnc codes .` command to generate codes about register fn into service and fn proxy.
    58  
    59  
    60  
    61  Note: the first argument type must be a `context.Context` and the second argument type must be a `struct`, the first
    62  return value type must be a `pointer` or `slice`, the second return value type must be `errors.CodeError`.
    63  
    64  Read [definition](https://github.com/aacfactory/fns/blob/main/docs/definition.md) for more.
    65  
    66  For example:
    67  
    68  ```go
    69  // GetArgument
    70  // @title Get user argument
    71  // @description Get user argument
    72  type GetArgument struct {
    73      // Id
    74      // @title User Id
    75      // @description User Id
    76      Id int64 `json:"id" validate:"required" message:"id is invalid"`
    77  }
    78  
    79  // User
    80  // @title User
    81  // @description User
    82  type User struct {
    83      // Id
    84      // @title User Id
    85      // @description User Id
    86      Id string `json:"id"`
    87      // Mobile
    88      // @title Mobile
    89      // @description Mobile
    90      Mobile string `json:"mobile"`
    91      // Name
    92      // @title Name
    93      // @description Name
    94      Name string `json:"name"`
    95      // Gender
    96      // @title Gender 
    97      // @enum F,M,N
    98      // @description Gender
    99      Gender string `json:"gender"`
   100      // Age
   101      // @title Age
   102      // @description Age
   103      Age int `json:"age"`
   104      // Avatar
   105      // @title Avatar
   106      // @description Avatar address
   107      Avatar string `json:"avatar"`
   108      // Active
   109      // @title Active
   110      // @description Active
   111      Active bool `json:"active"`
   112  }
   113  
   114  
   115  // get
   116  // @fn get
   117  // @validate true
   118  // @authorization true
   119  // @permission obj:act,obj_a:act_a
   120  // @internal false
   121  // @title Get user profile
   122  // @description >>>
   123  // Get user profile
   124  // ----------
   125  // errors:
   126  // | Name                     | Code    | Description                   |
   127  // |--------------------------|---------|-------------------------------|
   128  // | users_get_failed         | 500     | get user failed               |
   129  // <<<
   130  func get(ctx context.Context, argument GetArgument) (v *User, err errors.CodeError) {
   131      v = &User{
   132          Id:     fmt.Sprintf("%v", argument.Id),
   133          Mobile: "000",
   134          Name:   "foo",
   135          Gender: "F",
   136          Age:    10,
   137          Avatar: "https://foo.com/u/1/default.jpg",
   138          Active: true,
   139      }
   140      return
   141  }
   142  
   143  ```
   144  
   145  ## Register fn and generate fn proxy
   146  Direct access between functions is not recommended. Instead, proxy access is used.
   147  
   148  ```shell
   149  cd {project path}
   150  fnc codes .
   151  ```
   152  Or
   153  ```shell
   154  cd {project path}
   155  go generate
   156  ```
   157  
   158  In the above case, `users.Get` fn proxy will be generated. 
   159  
   160  ## Get websocket endpoint from context
   161  ```go
   162  socket, has := wss.GetWebsocketEndpoint(ctx)
   163  ```