# ad-magic-bff

**Repository Path**: apulisplatform/ad-magic-bff

## Basic Information

- **Project Name**: ad-magic-bff
- **Description**: ADMagic BFF
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: v1.6.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-10-26
- **Last Updated**: 2022-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bff-template

* BFF means "Backends for Frontends"
* 仅针对普通HTTP请求。sse/websocket/文件流等请求由其他服务管理

## 接口种类

1. 直接转发，可使用`internal/routers/redirect_utils.go`直接转发
2. http请求原子服务，使用`internal/httpclient/client.go`进行请求
3. 有些业务是异步处理的，需要监听rabbitmq，处理对应逻辑

## 项目结构说明

### 整体目录结构

参考文档[Standard Go Project Layout](https://github.com/golang-standards/project-layout)

* `cmd/`: 项目入口，main函数。
* `internal/`: 业务代码。internal为不需要被外部repo调用的代码，聚合层几乎都是业务逻辑，无需被外部引用。
* `deps/`: 本地依赖包。非公共仓库的。放在vendor文件夹执行`go mod vendor`会丢失文件，故放到不被go直接管理的文件夹下
* `api/`: openapi/swagger文档文件
* `docs/`: 项目设计文档
* `configs/`: config-template或默认config文件
* `build/`: 构建代码，如Dockerfile
* `deployments/`: 部署代码，如k8s yaml等

### 文件

* `go.mod`, `go.sum`: golang依赖管理代码
* `Makefile`: 常用命令
* `.gitmodules`: git submodule定义，通过`git submodule add`自动生成

### internal目录结构

* `configs`: 应用配置文件映射结构体
* `daos`：调用数据库逻辑代码
* `database`: 数据库驱动相关代码
* `middlewares`：中间件，如auth等
* `models`：数据库结构体定义
* `requests`：请求结构体定义
* `responses`：响应结构体定义
* `routers`：路由管理
* `services`：应用逻辑函数

## 生成swagger文档

1. 确保当前环境swag命令可以使用
    - 安装swag命令`go get -u github.com/swaggo/swag/cmd/swag`
    - 将`$GOPATH/bin`添加到`PATH`
2. 生成文档到api文件夹
    - `swag init -g cmd/api_server.go -o api`
3. 运行项目是查看swagger文档
    - `go run cmd/api_server.go`
    - 打开浏览器到`http://<HOST>:<PORT>/swagger/index.html`找到API文档
4. 导入到Yapi
    - 将步骤2生成在`api/`文件夹下的内容导入yapi

## git submodule管理

apulis代码日常托管在自建gitlab, 但部分代码可能开源至github，故mod命名统一以`github.com/apulis`开头

### 添加

使用`git submodule add`命令

```bash
git submodule add git@apulis-gitlab.apulis.cn:sdk/simple-gin-logger.git deps/simple-gin-logger
```

### go mod配置

在go.mod添加replace，用本地`deps`目录下的替换`github.com/apulis`相关依赖

```go
replace github.com/apulis/simple-gin-logger v0.0.0 => ./deps/simple-gin-logger
```

### 如本地没load代码，下载代码

```bash
git submodule init
git submodule update
```

## 调试和运行项目

1. 依照`config.template.yaml`编辑`config.yaml`文件
2. 运行`go run cmd/api_server.go`

## Makefile包含命令

* `get-deps`: 加载submodule, 并把第三方依赖下载到本地`vendor/`文件夹下
* `vet-check-all`: 使用go vet工具扫描代码(vet工具golang自带)
* `gosec-check-all`: 使用gosec工具扫描代码(gosec工具`go get github.com/securego/gosec/cmd/gosec`)
* `build-api-server-bin`: 构建二进制文件
* `build-api-server-docker`: 构建docker
* `gen-swagger`: 生成swagger文档

## 项目 api server 启动时，向 iam 注册 endpoints 示例
* iam 注册接口 yapi地址：http://yapi.apulis.cn:8444/project/250/interface/api/20671
* config 配置项
   ```go
   // intertal/configs/config.go
   type AAARegisterConfig struct {
	    RegisterOnStartUp bool      // api server 启动时 是否向iam注册
	    ModuleName        string    // 本模块名称   
	    RegisterApiUrl    string    // iam 注册接口 完整url  http://localhost:9999/iam/api/v1/endpoints
   }
   ```
* 注册函数调用说明
  ```go
  // internal/router/redirect_utils.go
  func RegisterToAAAEndPoints(action, method, endpoint string, roles ...string) gin.HandlerFunc
  /* function arguments
  action: action name; eg. adhub:dataset:get
  method: eg. get post put delete patch
  endpoint: url path; eg. /api/v1/adhub/datsets/{id}
  roles: SystemAdminRole OrgAdminRole DeveloperRole 
  */
  // 注册如下路由时，引入RegisterToAAAEndPoints
  // 为路由 /dataset/:id 增加 register endpoint，只有requests.DeveloperRole有权限
  routerGroup1.GET("/dataset/:id", ReverseProxy("http", "localhost:19999", "/api/v1/hello/:id"),
		RegisterToAAAEndPoints("adhub:dataset:get", "get", fmt.Sprintf("%s/%s", config.ApiV1Prefix, "/dataset/{id}"), requests.DeveloperRole))
  ```
* 为 所有路由 新增 RegisterToAAAEndPoints handler
* 在 `internal/routers/router.go` 会汇总所有的 endpoints及其对应权限, 调用 iam 注册接口
  ```go
    if configs.GetAppConfig().AAARegisterConf.RegisterOnStartUp {
        // request AAA endpoint registration API
        err := requestAAARegister(prebuild, configs.GetAppConfig().AAARegisterConf.RegisterApiUrl)
        if err != nil {
            logger.Fatalf("requestAAARegister error: %#v", err)
        }
    }
  ```