# 前言

通过之前的需求分析，可以知道整个工程架构是以 GitLab 为底层而搭建的 DevOps 系统，所以需要借助 GitLab 的 Open Api 将两个系统的信息互通串联。

本章将介绍如何使用 Egg 开发 GitLab Api 的工具类，并不涉及具体的业务代码。会对 GitLab 的授权、api 的使用有一个初步的了解，后期可以针对实际的业务需求做个性化定制与调整。

# Gitlab 授权

# 封装基础 GitLab Api 工具类

项目业务部分会通过 GitLab Api 获取对应的用户、项目信息，需要频繁地请求 GitLab Api，可以先将请求方法封装成统一的工具类方便后面使用。

详细的 api 请求方式这里不细说了，想要了解更多细节的同学们可以查看官方文档。

新建 /app/helper/utils/http.ts

const qs = require("qs");

const baseUrl = "https://gitlab.xxxxxx.com"; // 此处替换为你自己的 gitlab 地址

export default (app) => {
  return {
    async post({url, params = {}, query = {}}) {
      const sendUrl = `${baseUrl}${url}?${qs.stringify(query)}`;
      try {
        const { data, code } = await app.curl(sendUrl, {
          dataType: "json",
          method: "POST",
          data: params,
        });
        return { data, code };
      } catch (error) {
        return error;
      }
    },
    async methodV({ url, method, params = {}, query = {} }) {
      const sendUrl = `${baseUrl}/api/v4${url}?${qs.stringify(query)}`;
      try {
        const { data, code } = await app.curl(sendUrl, {
          dataType: "json",
          method,
          data: params,
        });
        return { data, code };
      } catch (error) {
        return error;
      }
    },
  };
};

@前端进阶之旅: 代码已经复制到剪贴板

上面封装的请求方法有两种，稍微注意一下，Gitlab Api 处理用户模块相关的 url 前缀是不带 ‘/api/v4’，而其他的业务请求是需要带上 ‘/api/v4’，因此会多封装一种不同类型的函数来请求对应的 Open Api。

# 认证授权

整个项目管理系统都是基于 GitLab 建立，要通过 Node 去调用 GitLab 获取对应仓库、用户等信息。

大多数API请求需要身份验证，或者只在没有提供身份验证时返回公共数据。由于项目需要获取更多的权限与信息，所以要拿到 GitLab 的授权。下面几种是 GitLab 提供的几种授权方式：

OAuth2 tokens
Personal access tokens
Project access tokens
Session cookie
GitLab CI/CD job token (Specific endpoints only)

考虑到安全、便捷等情况，项目选择 OAuth2 来进行授权（其他的适用场景多数用于制作 cli 工具类或者脚本拉取项目进行构建等操作）。

OAuth2 授权有以下三种方式：

Resource owner password credentials flow（客户端用户密码验证授权）
Web application flow（Web 应用程序授权）
Implicit grant flow（隐式授权流）

最新的 GitLab 的文档已经更新了，现在的 GitLab 的版本是 13，本章教程是按照 12 来写的，但这并不影响项目的正常开发，有兴趣的同学可以看看最新的授权文档。

项目将使用第 1、2 种方式来进行 OAuth2 授权。

# Resource owner password credentials flow

客户端用户密码验证授权顾名思义，可以使用 GitLab 的用户名/密码直接通过请求从 GitLab 换取 access_token。

先从简单的用户名/密码授权开始进行 OAuth2 授权。

首先创建 /app/controller/user.ts，粘贴以下代码：

import { Controller } from 'egg';
import { Post, Prefix } from 'egg-shell-decorators';

@Prefix('user')
export default class UserController extends Controller {
  @Post('/getUserToken')
  public async getUserToken({
    request: {
      body: { params },
    },
  }) {
    const { ctx } = this;
    const { username, password } = params;

    // gitLab 获取 access_token
    const userToken = await ctx.service.user.getUserToken({
      username,
      password,
    });

    this.ctx.body = userToken;
  }
}

@前端进阶之旅: 代码已经复制到剪贴板

创建 /app/service/user.ts，粘贴以下代码：

import { Service } from 'egg';

export default class User extends Service {

  public async getUserToken({ username, password }) {
    const { data: token } = await this.ctx.helper.utils.http.post({
      url: '/oauth/token',
      params: {
        grant_type: 'password',
        username,
        password,
      },
    });

    if (token && token.access_token) {
      return token;
    }
    return false;
  }
}

@前端进阶之旅: 代码已经复制到剪贴板

使用 Postman 请求 http://127.0.0.1:7001/user/getUserToken，输入对应的 GitLab 的用户密码，可以获取到 OAuth2 access_token，然后通过 access_token 调用对应的 Open Api 即可拿到想要的信息。

这样有个缺点，及时用户当前的 GitLab 已登陆，仍需要用户重新输入用户名、密码才能登陆项目，且可能存在相互用户信息不对称（两个系统登录了不同的用户）。

# Web application flow

如果你拥有 GitLab 管理员权限的时候，那么使用 Web 应用程序授权将是非常方便的。流程是通过 GitLab 直接授权回调拿到 access_token，这样就不需要两个项目都登录一遍，提高用户体验，也避免出现两个系统账号不一致的情况。

再次在 controller/user.ts 与 service/user.ts 添加对应的方法，复制下面代码：

// /app/controller/user.ts
@Get('/getTokenByApp')
  public async getTokenByApplications({
    request: {
      query: { code },
    },
  }) {
    const { ctx } = this;
    // gitLab 获取 access_token
    const userToken = await ctx.service.user.getTokenByApplications({ code });
    this.ctx.body = userToken;
  }

// /app/service/user.ts
 public async getTokenByApplications({ code }) {
   const { data: token } = await this.ctx.helper.utils.http.post({
      url: '/oauth/token',
      params: {
        grant_type: 'authorization_code',
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
        code,
        redirect_uri: 'http://127.0.0.1:7001/user/getTokenByApp',
      },
    });

    if (token && token.access_token) {
      return token;
    }
    return false;
  }

@前端进阶之旅: 代码已经复制到剪贴板

由于 GitLab 授权是直接浏览器携带 code 参数重定向到指定的 Redirect Uri，所以 http://127.0.0.1:7001/user/getTokenByApp 使用 Get 方式请求。

使用管理员账号登陆之后，输入 Name（随便取），Redirect URI:http://127.0.0.1:7001/user/getTokenByApp。

因为是实战项目，直接将除了 trusted ，scopes 里面的其他选型全部都选中，不需要后面再次修改。(实际场景中，可能需要多种 application 组合使用，每个 application 的授权都不一样，配合业务选择合适的权限使用，不过一般都只使用 api 即可)

将得到的参数填入 service/user.ts 里面的 getTokenByApplications 方法。

Application Id 填入方法里面的 client_id
Secret 填入 client_secret
Callback Uri 填入 redirect_uri

浏览器输入 http://192.168.160.88:8888/oauth/authorize?client_id=CLIENT_ID&redirect_uri=http://127.0.0.1:7001/user/getTokenByApp&response_type=code（其中 client_id 替换成自己获取）。

不出意外的话，将会出现 GitLab 的授权页面

点击授权之后，GitLab 会携带 code 重定向到上述地址，然后可以通过 code 换取 access_token，再继续进行剩下的获取用户信息操作。

如果没有出现授权界面，而是直接重定向了，应该是配置的时候将 trusted 选项勾选了，重新修改一下配置，或者不管都行，这毕竟只是一个 demo，可以给予完全的信任。

# 封装 GitLab Api 业务请求

GitLab 的 Api 文档涵盖的内容非常多，先将必备的一些文档提取出来，根据文档描述来封装对应的业务请求，如果想了解更多的同学也可以自行阅读 GitLab Api。

# GitLab Api 通用文档简介

# 请求类型

请求类型	描述
GET	访问一个或多个资源并以JSON形式返回结果
POST	如果资源成功创建，则返回 201，并以JSON形式返回新创建的资源
GET / PUT	如果资源被成功访问或修改，则返回 200。(修改后的)结果以JSON的形式返回
DELETE	删除成功返回 204

# 前言

# Gitlab 授权

# 封装基础 GitLab Api 工具类

# 认证授权

# Resource owner password credentials flow

# Web application flow

# 封装 GitLab Api 业务请求

# GitLab Api 通用文档简介

# 请求类型

# 状态码

Node 工具篇 Gitlab Api|Node Devops专题

Node 工具篇 Gitlab Api|Node Devops专题