dst-standard-framework

v1.0.2

Published

2 years ago

## 快速入门本框架提供了基础的开发流程，包含了定时任务、Redis、拦截注入日志、特定接口客户端请求转发、以及接口拦截等样例，多请求实例封装，针对不同服务配置不同公用参数和处理标准化多返回结果，能够有效的提升研发效率。基于 midway、egg ,如需进一步了解，参见 [midway 文档][midway]。

Downloads

0High
0Medium
0Low

dobbly

地上铁前端服务框架

快速入门

本框架提供了基础的开发流程，包含了定时任务、Redis、拦截注入日志、特定接口客户端请求转发、以及接口拦截等样例，多请求实例封装，针对不同服务配置不同公用参数和处理标准化多返回结果，能够有效的提升研发效率。基于 midway、egg ,如需进一步了解，参见 midway 文档。

环境配置

推荐使用 Macbook Pro M1 16G
Node.js 保持 16.18.0 LTS 版本
~~Intellj IDEA Community 暂不可用~~

快速开始

用 Webstorm 从仓库拉取脚手架项目，然后在项目中打开 package.json 找到 scripts 点击左侧绿色运行按钮执行一次 'dev' 脚本，即可配置好环境。

研发插件

地上铁前端微服务标准化插件，减少繁琐的人工复制，简化研发流程。下载插件插件说明

格式化代码

由于开发环境配置的差异性，代码检查的时候请开启 Prettier 优化您的代码以减少编译器的报错，操作路径如下： WebStorm -> Preferences -> Languages & Frameworks -> JavaScript -> Prettier On Reformat Code action ✅ On save ✅

文件结构

/logs 本地开发时日志存放目录（部署后建议使用自定义目录）
/config 配置文件不同环境自定义配置项在此
/src/auto 自动加载任务，用于服务初始化和自动执行
/src/config midway 配置项
/src/controller 控制器，配置路由以及解析用户输入处理返回结果
/src/decorator 自定义属性、方法、参数装饰器
/src/error 自定义错误
/src/filter 自定义异常、全局异常捕获处理
/src/guard 守卫配置，进入路由之前进行任务处理
/src/middleware 中间件进入控制器之前或者之后的逻辑处理
/src/queue 定时任务和队列
/src/service 服务，业务逻辑抽象出来保持独立性
/src/utils 工具类存放

接口文档

框架默认启用 Swagger 文档自动生成访问地址：http://localhost:8080/swagger-ui/index.html

装饰器

ClientFactory 装饰器会自动注入一个对应名称的 HttpService 单例，该实例用于请求对应的服务

@ClientFactory('mocha')
mochaService : HttpService

请求三方服务

已封装好数据，可根据需要选择是否要携带客户端请求的 headers 信息请求目标服务。

this.mochaService.request({
  url: '/member/index',
  method: 'GET',
  headers: this.ctx.clientHeaders,
});

格式化日志输出

关于 HttpService 的初始化统一在 /src/auto/axios.autoload.ts 进行配置 HttpService 配置好日志拦截器将输出格式化后的请求日志

//config host 属性下对应的实例 log:true 将开启实例日志输出
{
  "id":
  "mocha",
  "name":"摩卡",
  "log":true
}

2022-10-25 10:12:46,101 INFO 21857 -------------------- Http Request --------------------
2022-10-25 10:12:46,101 INFO 21857 {"url":"https://m.test.dstzc.com/apply-apis/v3/member/index (GET Method)","headers":null,"params":{},"body":null}
2022-10-25 10:12:46,101 INFO 21857 -------------------- Http Request --------------------

2022-10-25 10:12:46,244 INFO 21857 -------------------- Http Response --------------------
2022-10-25 10:12:46,244 INFO 21857 {"status":200,"url":"https://m.test.dstzc.com/apply-apis/v3/member/index (GET Method)","body":{"code":-1,"msg":"缺少版本号","data":[]}}
2022-10-25 10:12:46,244 INFO 21857 -------------------- Http Response ---

HttpService 配置好业务异常处理流程，请求服务出现业务异常会被错误日志捕获并存档。

//config 目录下配置好业务参数将开启自动异常处理
{
  "id":
  "mocha",
  "name":"摩卡",
  "codeValueSuccess":0,
  "codeKey":
  "code",
  "messageKey":"msg"
}

2022-10-24 18:30:58,750 ERROR 69016 [-/127.0.0.1/-/4ms GET /v1/api/getUserInfo] BusinessError: token不能为空
    at AuthGuard.canActivate (/Users/luoyuan/WebstormProjects/dst-front-end-service/src/guard/auth.userinfo.ts:19:13)
    at GuardManager.runGuard (/Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/@midwayjs/core/dist/common/guardManager.js:28:46)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async Object.<anonymous> (/Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/@midwayjs/core/dist/common/webGenerator.js:27:34)
    at async /Users/luoyuan/WebstormProjects/dst-front-end-service/src/middleware/response.middleware.ts:14:22
    at async /Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/@midwayjs/i18n/dist/middleware.js:150:17
    at async xframe (/Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/egg-security/lib/middlewares/xframe.js:7:5)
    at async xssProtection (/Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/egg-security/lib/middlewares/xssProtection.js:7:5)
    at async nosniff (/Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/egg-security/lib/middlewares/nosniff.js:8:5)
    at async noopen (/Users/luoyuan/WebstormProjects/dst-front-end-service/node_modules/egg-security/lib/middlewares/noopen.js:8:5) {
  code: '401',
  cause: undefined,
  status: 401
}

在请求到我们的API经过中间件后，会将请求的 Request 以及 Response 日志输出，例如：

2022-10-28 15:38:42,864 INFO 82888 -------------------- Client Request --------------------
2022-10-28 15:38:42,865 INFO 82888 {"url":"/v1/api/getUserInfo (POST Method)","headers":{"host":"127.0.0.1:8080","connection":"keep-alive","content-length":"0","sec-ch-ua":"\"Chromium\";v=\"106\", \"Google Chrome\";v=\"106\", \"Not;A=Brand\";v=\"99\"","accept":"*/*","sec-ch-ua-mobile":"?0","user-agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36","sec-ch-ua-platform":"\"macOS\"","origin":"http://127.0.0.1:8080","sec-fetch-site":"same-origin","sec-fetch-mode":"cors","sec-fetch-dest":"empty","referer":"http://127.0.0.1:8080/swagger-ui/index.html","accept-encoding":"gzip, deflate, br","accept-language":"zh-CN,zh;q=0.9","cookie":"locale=zh-cn"},"params":{},"body":{}}
2022-10-28 15:38:42,866 INFO 82888 -------------------- Client Request --------------------

··················

2022-10-28 15:38:43,031 INFO 82888 [-/127.0.0.1/-/171ms POST /v1/api/getUserInfo] -------------------- Client Response --------------------
2022-10-28 15:38:43,031 INFO 82888 [-/127.0.0.1/-/171ms POST /v1/api/getUserInfo] {"status":200,"path":"/v1/api/getUserInfo (POST Method)","body":{"code":"-1","message":"缺少版本号","data":null}}
2022-10-28 15:38:43,031 INFO 82888 [-/127.0.0.1/-/171ms POST /v1/api/getUserInfo] -------------------- Client Response --------------------

结合 HttpService 日志，我们可以看到一个完整的请求链路信息，顺序如下所示： Client Request (用户请求入参) -> Http Request (请求三方服务入参) -> Http Response (请求三方服务响应结果) -> Client Response (返回最终结果) 上述流程为一次标准的接口转发流程，实际业务场景区别可能多次请求三方服务，略有差异。

常量配置

在 /config 目录下以环境名称存储配置文件 localhost.json 通过 config 自动获取对应环境的常量配置。

{
  "title":"本地环境",
    "hosts":[
    {
      "id": "mocha",
      "name": "摩卡",
      "log": true,
      "baseUrl": "https://m.test.dstzc.com/apply-apis/v3",
      "codeValueSuccess": 0,
      "codeKey": "code",
      "messageKey": "msg"
    }
  ]
}

使用config库取出对应环境常量配置信息：

import * as config from 'config';

config()
{
  const title = config.get('title')
}

常见问题

com.netflix.client.ClientException: Load balancer does not have available server for client 没有可用的服务,需要联系对应业务线同学解决。
org.springframework.web.HttpMediaTypeNotSupportedException: Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported POST请求 data 不可以传递 null 参数，至少需要空对象 {} 。

本地开发

$ npm i
$ npm run dev
$ open http://localhost:8080/

部署

$ npm start
$ npm stop

内置指令

使用 npm run lint 来做代码风格检查。
使用 npm test 来执行单元测试。

规划中

IntelJ 插件一键生成服务和控制器代码
更友好便捷的前端 Mock 能力