最近在做运营侧中台项目的重构,目前的选型是 koa2+typescript。在实际生产中,切实体会到了 typescript 类型带来的好处。
为了更形象说明 typescript 的优势,还是先来看一个场景吧:
BUG 现场
作为一门灵活度特别大的语言,坏处就是:
复杂逻辑编写过程中,数据结构信息可能由于逻辑复杂、人员变更等情况而丢失,从而写出来的代码含有隐含错误
。
比如这次我在给自己的博客编写node 脚本的时候就遇到了这种情况:
const result = [];
function findAllFiles(root) {
const files = fs.readdirSync(root);
files.forEach(name => {
const file = path.resolve(root, name);
if (isFolder(file)) {
findAllFiles(file);
} else {
result.push({
path: file,
check: false,
content: fs.readFileSync(file)
});
}
});
}
result 保存了递归遍历的所有文件的 path、check、content 信息,其中 content 信息会被传给prettier.js的check(content: string, options: object)方法。
显然,上述代码是有错误的,但是极难发现。只有运行它的时候,才能通过堆栈报错来进行定位。但如果借助 ts,就可以立即发现错误,保持代码稳健。
这个问题放在文章最后再说,下面看看 ts 在 koa 项目中的运用吧。
项目目录
由于没有历史包袱,整个项目的架构还是非常清爽的。如下所示:
.
├── README.md
├── bin # 存放scripts的脚本文件
├── dist # 编译打包后的js文件
├── docs # 详细文档
├── package.json # npm
├── sh # pm2等脚本
├── src # 项目源码
├── tmp # 存放临时文件的地方
└── tsconfig.json # typescript编译配置
typescript 编译与 npm 配置
因为是用 ts 来编写代码,因此需要专门编写 typescript 的配置文件:tsconfig.json。根据个人习惯,以及之前组内的 ts 项目,配置如下:
{
"compilerOptions": {
"module": "commonjs", // 编译生成的模块系统代码
"target": "es2017", // 指定ecmascript的目标版本
"noImplicitAny": true, // 禁止隐式any类型
"outDir": "./dist",
"sourceMap": false,
"allowJs": false, // 是否允许出现js
"newLine": "LF"
},
"include": ["src/**/*"]
}
对于一些有历史遗留的项目,或者说用 js 逐步重构为 ts 的项目来说,由于存在大量的 js 遗留代码,因此allowJs这里应该为true,noImplicitAny应该为false。
在package.json中,配置两个脚本,一个是 dev 模式,另一个是 prod 模式:
{
"scripts": {
"dev": "tsc --watch & export NODE_ENV=development && node bin/dev.js -t dist/ -e dist/app.js",
"build": "rm -rf dist/* && tsc"
}
}
在 dev 模式下,需要 tsc 监听配置中include中指定的 ts 文件的变化,并且实时编译。bin/dev.js是根据项目需要编写的监听脚本,它会监听dist/目录中编译后的 js 文件,一旦有满足重启条件,就重启服务器。
类型声明文件
koajs 与常见插件的类型声明都要在@types 下安装:
npm i --save-dev @types/koa @types/koa-router @types/koa2-cors @types/koa-bodyparser
区分 dev/prod 环境
为了方便之后的开发和上线,src/config/目录如下:
.
├── dev.ts
├── index.ts
└── prod.ts
配置分为 prod 和 dev 两份。dev 模式下,向控制台打印信息;在 prod 下,需要向指定位置写入日志信息。类似的,dev 下不需要进行身份验证,prod 下需要内网身份验证。因此,利用 ts 的extends特性来复用数据声明:
// mode: dev
export interface ConfigScheme {
// 监听端口
port: number;
// mongodb配置
mongodb: {
host: string;
port: number;
db: string;
};
}
// mode: prod
export interface ProdConfigScheme extends ConfigScheme {
// 日志存储位置
logRoot: string;
}
在 index.ts 中,通过process.env.NODE_ENV变量值来判断模式,进而导出对应的配置。
import { devConf } from "./dev";
import { prodConf } from "./prod";
const config = process.env.NODE_ENV === "development" ? devConf : prodConf;
export default config;
如此,外界直接引入即可。但在开发过程中,例如身份认证中间件。虽然 dev 模式下不会开启,但编写它的时候,引入的config类型是ConfigScheme,在访问ProdConfigScheme上的字段时候 ts 编译器会报错。
这时候,ts 的断言就派上用场了:
import config, { ProdConfigScheme } from "./../config/";
const { logRoot } = config as ProdConfigScheme;
中间件编写
对于整体项目,和 koa 关联较大的业务逻辑主要体现在中间件。这里以运营系统必有的「操作留存中间件」的编写为例,展示如何在 ts 中编写中间件的业务逻辑和数据逻辑。
引入 koa 以及编写好的轮子:
import * as Koa from "koa";
import { print } from "./../helpers/log";
import config from "./../config/";
import { getDB } from "./../database/mongodb";
const { mongodb: mongoConf } = config; // mongo配置
const collectionName = "logs"; // 集合名称
操作留存中需要留存的数据字段有:
staffName: 操作人
visitTime: 操作时间
url: 接口地址
params: 前端传来的所有参数
ts 中借助 interface 直接约束字段类型即可。一目了然,对于之后的维护者来说,基本不需要借助文档,即可理解我们要和 db 交互的数据结构。
interface LogScheme {
staffName: string;
visitTime: string;
url: string;
params?: any;
}
最后,编写中间件函数逻辑,参数需要指明类型。当然,直接指明参数是 any 类型也可以,但这样和 js 就没差别,而且也体会不到 ts 带来文档化编程的好处。
因为之前已经安装了@types/koa,因此这里不需要我们手动编写 .d.ts 文件。并且,koa 的内置数据类型已经被挂在了前面 import 进来的Koa上了(是的,ts 帮我们做了很多事情)。上下文的类型就是 Koa.BaseContext,回调函数类型是() => Promise
async function logger(ctx: Koa.BaseContext, next: () => Promise<any>) {
const db = await getDB(mongoConf.db); // 从db链接池中获取链接实例
if (!db) {
ctx.body = "mongodb errror at controllers/logger";
ctx.status = 500;
return;
}
const doc: LogScheme = {
staffName: ctx.headers["staffname"] || "unknown",
visitTime: Date.now().toString(10),
url: ctx.url,
params: ctx.request.body
};
// 不需要await等待这段逻辑执行完毕
db.collection(collectionName)
.insertOne(doc)
.catch(error =>
print(`fail to log info to mongo: ${error.message}`, "error")
);
return next();
}
export default logger;
单元函数
这里以一个日志输出的单元函数为例,说一下「索引签名」的应用。
首先,通过联合类型约束了日志级别:
type LogLevel = "log" | "info" | "warning" | "error" | "success";
此时,打算准备一个映射:日志等级 => 文件名称 的数据结构,例如 info 级别的日志对应输出的文件就是 info.log。显然,这个 object 的所有 key,必须符合 LogLevel。写法如下:
const localLogFile: {
[level in LogLevel]: string | void;
} = {
log: "info.log",
info: "info.log",
warning: "warning.log",
error: "error.log",
success: "success.log"
};
如果对于 log 级别的日志,不需要输出到文件仅仅需要打印到控制台。那么localLogFile应该没有log字段,如果直接去掉log字段,ts 编译器报错如下:
Property 'log' is missing in type '{ info: string; warning: string; error: string; success: string; }' but required in type '{ log: string | void; info: string | void; warning: string | void; error: string | void; success: string | void; }'.
根据错误,这里将索引签名字段设置为「可选」即可:
const localLogFile: {
[level in LogLevel]?: string | void;
} = {
info: "info.log",
warning: "warning.log",
error: "error.log",
success: "success.log"
};
关于 export
使用export导出复杂对象时候,请加上类型声明,不要依赖与 ts 的类型推断。
index.ts:
import level0 from "./level0";
export interface ApiScheme {
method: ApiMethod;
host: string;
}
export interface ApiSet {
[propName: string]: ApiScheme;
}
export const apis: ApiSet = {
...level0
};
level0.ts:
import { ApiSet } from "./index";
// 声明导出对象的数据类型
export const level0: ApiSet = {
"qcloud.tcb.getPackageInfo": {
method: "post",
host: tcb.dataUrl
},
"qcloud.tcb.getAlarmRecord": {
method: "post",
host: tcb.dataUrl
}
};
回到开头
回到开头的场景,如果用 typescript,我们会先声明result中每个对象的格式:
interface FileInfo {
path: string;
check: boolean;
content: string;
}
const result: FileInfo[] = [];
此时,你会发现 typescript 编译器已经给出了报错,在 content: fs.readFileSync(file) 这一行中,报错信息如下:
不能将类型“Buffer”分配给类型“string”。
如此,在编写代码的时候,就能立即发现错误。而不是写了几百行,然后跑起来后,根据堆栈报错一行行去定位问题。
仔细想一下,如果是 30 个人合作的大型 node/前端项目,出错的风险会有多高?定位错误成本会有多高?所以,只想说 ts 真香!