github.com/isyscore/isc-gobase@v1.5.3-0.20231218061332-cbc7451899e9/server/README.md (about)

     1  
     2  # server
     3  server包是用于更加方便的开发web项目而封装的包，开启配置的话，如下
     4  
     5  ### 简单示例
     6  ```yaml
     7  # application.yml 内容
     8  base:
     9    server:
    10      # 是否启用，默认：false
    11      enable: true
    12  ```
    13  ```go
    14  package main
    15  
    16  import (
    17      "github.com/gin-gonic/gin"
    18      "github.com/isyscore/isc-gobase/server"
    19      "github.com/isyscore/isc-gobase/server/rsp"
    20  )
    21  
    22  func main() {
    23      server.Get("api/get", GetData)
    24      server.Run()
    25  }
    26  
    27  func GetData(c *gin.Context) {
    28      rsp.SuccessOfStandard(c, "value")
    29  }
    30  ```
    31  运行如下
    32  ```shell
    33  root@user ~> curl http://localhost:8080/api/get
    34  {"code":0,"data":"value","message":"success"}
    35  ```
    36  
    37  ## 全部配置
    38  
    39  isc-gobase项目内置的一些server的配置
    40  ```yaml
    41  api-module: sample
    42  
    43  base:
    44    api:
    45      # api前缀，默认包含api前缀，如果路径本身有api，则不再添加api前缀
    46      prefix: /api
    47    application:
    48      # 应用名，默认为空
    49      name: isc-gobase-demo
    50      # 服务版本号
    51      version: vx.x.xx
    52    server:
    53      # 是否启用，默认：true
    54      enable: true
    55      # 端口号，默认：8080
    56      port: 8080
    57      gin:
    58        # 有三种模式：debug/release/test，默认 release
    59        mode: debug
    60        pprof:
    61          # pprof开关是否可以开启，默认false
    62          enable: false
    63      cors:
    64        # 是否启用跨域配置，默认启用
    65        enable: true
    66      request:
    67        print:
    68          # 是否打印：true, false；默认 false
    69          enable: false
    70          # 打印的话日志级别，默认debug
    71          level: info
    72          # 指定要打印请求的uri
    73          include-uri:
    74            - /xxx/x/xxx
    75            - /xxx/x/xxxy
    76          # 指定不打印请求的uri
    77          exclude-uri:
    78            - /xxx/x/xxx
    79            - /xxx/x/xxxy
    80      response:
    81        print:
    82          # 是否打印：true, false；默认 false
    83          enable: false
    84          # 打印的话日志级别，默认debug
    85          level: info
    86          # 指定要打印请求的uri
    87          include-uri:
    88            - /xxx/x/xxx
    89            - /xxx/x/xxxy
    90          # 指定不打印请求的uri
    91          exclude-uri:
    92            - /xxx/x/xxx
    93            - /xxx/x/xxxy
    94      exception:
    95        # 异常返回打印
    96        print:
    97          # 是否启用：true, false；默认 false
    98          enable: true
    99          # 一些异常httpStatus不打印；默认可不填
   100          exclude:
   101            - 408
   102            - 409
   103      # 版本号设置,默认值:unknown
   104      version: 1.0.0
   105    swagger:
   106      # 是否开启swagger：true, false；默认 false
   107      enable: false
   108  ```
   109  isc-gobase项目内置的一些endpoint端口
   110  ```shell
   111  base:
   112    # 内部开放的 endpoint
   113    endpoint:
   114      # 健康检查处理，默认关闭，true/false
   115      health:
   116        enable: true
   117      # 配置的管理（查看和变更），默认关闭，true/false
   118      config:
   119        enable: true
   120      # bean的管理（属性查看、属性修改、函数调用），默认false
   121      bean:
   122        enable: true
   123  ```
   124  
   125  ### api.prefix和api-module介绍
   126  其中api和api-module这个配置最后的url前缀是<br/>
   127  {api.prefix}/{api-module}/业务代码
   128  
   129  比如如上：
   130  
   131  ```shell
   132  root@user ~> curl http://localhost:8080/api/sample/get/data
   133  {"code":0,"data":"ok","message":"success"}
   134  ```
   135  
   136  ### server介绍
   137  额外说明：
   138  提供request和response的打印，用于调试时候使用
   139  ```shell
   140  # 开启请求的打印，开启后默认打印所有请求，如果想打印指定uri，请先配置uri
   141  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.enable", "value":"true"}'
   142  # 开启响应的打印
   143  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.enable", "value":"true"}'
   144  # 开启异常的打印
   145  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.exception.print.enable", "value":"true"}'
   146  ```
   147  
   148  #### 指定uri打印
   149  如果不指定uri则会默认打印所有的请求
   150  ```shell
   151  # 指定要打印的请求的uri
   152  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.include-uri[0]", "value":"/api/xx/xxx"}'
   153  # 指定不要打印的请求uri
   154  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.exclude-uri[0]", "value":"/api/xx/xxx"}'
   155  
   156  # 指定要打印的响应的uri
   157  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.include-uri[0]", "value":"/api/xx/xxx"}'
   158  # 指定不要打印的响应uri
   159  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.exclude-uri[0]", "value":"/api/xx/xxx"}'
   160  ```
   161  
   162  提示：<br/>
   163  - 如果"请求"和"响应"都开启打印，则只会打印"响应"，因为响应中已经包括了"请求"
   164  - 指定多个uri的话，如下，配置其实是按照properties的方式进行指定的
   165  ```shell
   166  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.include-uri[0]", "value":"/api/xx/xxx"}'
   167  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.include-uri[1]", "value":"/api/xx/xxy"}'
   168  curl -X PUT http://localhost:xxx/{api-prefix}/{api-module}/config/update -d '{"key":"base.server.request.print.include-uri[2]", "value":"/api/xx/xxz"}'
   169  ...
   170  ```
   171  ## swagger 使用介绍
   172  如果想基于 gobase 来使用 swagger 这里需要按照如下步骤来处理
   173  
   174  #### 1. 安装命令
   175  这个是 go-swagger 必需
   176  ```shell
   177  go install github.com/swaggo/swag/cmd/swag
   178  ```
   179  #### 2. 添加注解
   180  这里按照go-swagger官网的注解进行编写即可，比如
   181  
   182  ```go
   183  // @Summary xxx
   184  // @title xxx
   185  // @Tags xxx
   186  // @Router /api/xx/xx/xxxx/xxx [post]
   187  // @param param body Addxxxx true "用户请求参数"
   188  // @Success 200 {object} any
   189  ```
   190  
   191  #### 3. 生成swagger文件
   192  这里按照go-swagger官网的注解进行编写即可
   193  ```shell
   194  swag init
   195  ```
   196  #### 4. 添加swagger的doc引入
   197  执行命令`swag init`后会生成`docs`文件夹，里面有相关的swagger配置。这里需要代码显示的引入，否则swagger解析不出来，建议在`main.go`中引入，示例：
   198  ```go
   199  package main
   200  
   201  import (
   202      "github.com/isyscore/isc-gobase/server"
   203      // 这里：不引入就会在swagger生成的页面中找不到doc.json文件 
   204      _ "isc-xx-service/docs"
   205  )
   206  
   207  // @Title xxx
   208  // @Version 1.0.0
   209  func main() {
   210      server.Run()
   211  }
   212  ```
   213  
   214  #### 5. 开启开关，运行程序
   215  代码开启如下开关
   216  ```yaml
   217  base:
   218    swagger:
   219      enable: true
   220  ```
   221  启动程序后，打开网页即可看到
   222  ```shell
   223  http://xxxx:port/swagger/index.html
   224  ```
   225  
   226  ### 问题
   227  如果遇到如下问题，则执行下如下即可
   228  ```shell
   229  ../../../go/src/pkg/mod/github.com/swaggo/swag@v1.8.5/gen/gen.go:18:2: missing go.sum entry for module providing package github.com/ghodss/yaml (imported by github.com/swaggo/swag/gen); to add:
   230          go get github.com/swaggo/swag/gen@v1.8.5
   231  ../../../go/src/pkg/mod/github.com/swaggo/swag@v1.8.5/cmd/swag/main.go:10:2: missing go.sum entry for module providing package github.com/urfave/cli/v2 (imported by github.com/swaggo/swag/cmd/swag); to add:
   232          go get github.com/swaggo/swag/cmd/swag@v1.8.5
   233  ```
   234  执行
   235  ```shell
   236  go get github.com/swaggo/swag/gen
   237  go get github.com/swaggo/swag/cmd/swag
   238  ```