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

     1  # 使用
     2  
     3  ---
     4  
     5  ## 创建访问
     6  1. 在`modules`下创建服务包
     7  2. 在服务包下创建 `doc.go`
     8  
     9  举例：
    10  ```go
    11  // Package users
    12  // @service users
    13  // @title Users
    14  // @description User service
    15  // @internal false
    16  package users
    17  ```
    18  
    19  ## 创建服务组件（如果需要的话）
    20  
    21  在服务包下创建 `{component name}` 包。
    22  然后在`component`包下创建实现了 `service.Component`的组件，
    23  最后创建 `components.go` 并打上 `@component`来把它注册到服务中。
    24  组件在大多数情况下是不需要的，除非服务中集成了第三方服务。
    25  
    26  
    27  组件解构:
    28  
    29  ```text
    30  |-- {service dir}
    31      |-- {component name}
    32          |-- component.go
    33      |-- components.go
    34  ```
    35  
    36  component.go
    37  
    38  ```go
    39  type Foo struct {
    40  }
    41  
    42  func (c *Foo) Name() (name string) {
    43      name = "component_name"
    44      return
    45  }
    46  
    47  func (c *Foo) Build(options service.ComponentOptions) (err error) {
    48      // build with config
    49      return
    50  }
    51  
    52  func (c *Foo) Close() {
    53      return
    54  }
    55  ```
    56  
    57  components.go, value of `@component` is keypair, key is component_name, value is component position.
    58  
    59  ```go
    60  // fooLoader
    61  // @component {component_name}:{package}.Foo
    62  func fooLoader() service.Component {
    63  return &foo.Foo{}
    64  }
    65  ```
    66  
    67  ## 创建函数
    68  
    69  在服务包下创建一个私有函数。
    70  
    71  阅读 [definition](https://github.com/aacfactory/fns/blob/main/docs/definition_zh.md) 获取更多信息。
    72  
    73  举例:
    74  
    75  ```go
    76  // GetArgument
    77  // @title Get user argument
    78  // @description Get user argument
    79  type GetArgument struct {
    80      // Id
    81      // @title User Id
    82      // @description User Id
    83      Id int64 `json:"id" validate:"required" message:"id is invalid"`
    84  }
    85  
    86  // User
    87  // @title User
    88  // @description User
    89  type User struct {
    90      // Id
    91      // @title User Id
    92      // @description User Id
    93      Id string `json:"id"`
    94      // Mobile
    95      // @title Mobile
    96      // @description Mobile
    97      Mobile string `json:"mobile"`
    98      // Name
    99      // @title Name
   100      // @description Name
   101      Name string `json:"name"`
   102      // Gender
   103      // @title Gender 
   104      // @enum F,M,N
   105      // @description Gender
   106      Gender string `json:"gender"`
   107      // Age
   108      // @title Age
   109      // @description Age
   110      Age int `json:"age"`
   111      // Avatar
   112      // @title Avatar
   113      // @description Avatar address
   114      Avatar string `json:"avatar"`
   115      // Active
   116      // @title Active
   117      // @description Active
   118      Active bool `json:"active"`
   119  }
   120  
   121  
   122  // get
   123  // @fn get
   124  // @validate true
   125  // @authorization true
   126  // @permission foo,bar
   127  // @internal false
   128  // @title Get user profile
   129  // @description >>>
   130  // Get user profile
   131  // ----------
   132  // errors:
   133  // | Name                     | Code    | Description                   |
   134  // |--------------------------|---------|-------------------------------|
   135  // | users_get_failed         | 500     | get user failed               |
   136  // <<<
   137  func get(ctx context.Context, argument GetArgument) (v *User, err errors.CodeError) {
   138      v = &User{
   139          Id:     fmt.Sprintf("%v", argument.Id),
   140          Mobile: "000",
   141          Name:   "foo",
   142          Gender: "F",
   143          Age:    10,
   144          Avatar: "https://foo.com/u/1/default.jpg",
   145          Active: true,
   146      }
   147      return
   148  }
   149  
   150  ```
   151  
   152  ## 注册函数和创建函数代理
   153  直接访问函数是不建议的，那会失去很多特性，所以请使用函数代理的访问访问。
   154  
   155  ```shell
   156  cd {project path}
   157  fnc codes .
   158  ```
   159  Or
   160  ```shell
   161  cd {project path}
   162  go generate
   163  ```
   164  
   165  在上述例子中， `users.Get` 函数代理会被生成。
   166  
   167  ## 从上下文中获取 WEBSOCKET ENDPOINT
   168  ```go
   169  socket, has := wss.GetWebsocketEndpoint(ctx)
   170  ```