[See How]全栈Node TS框架TSRPC实践教程（一）

博客和公众号

此文已同步到因卓诶博客，请大家关注同名公众号

[See How]全栈Node TS框架TSRPC实践教程（一）www.yinzhuoei.com

前言

某个普通的一天的早晨，水友群的小姐姐和我聊前端架构，因为她们组最近要筹备一些新项目，在做架构的中途出现了很多问题，所以我拿到了她们的架构项目脚手架代码。拿到代码之后我发现深圳那边的前端团队普遍做的很好，有先进的架构思想，也把ts用的很纯粹，最后没帮人家解决问题，反倒是自己学到了不少。最后我们聊到了前后端全栈开发，如何动态校验协议参数等问题，因为熟悉我开源项目（剑指题解）的朋友都知道，我的后端代码尤其是动态校验那块写的是真差，为了ts而用ts，这也是目前很多用ts的小伙伴的通病，所以我一直打算重构我的一部分后端代码，这个时候见多识广的小姐姐就推荐给我了一个框架，这个框架也是[see how]系列第一篇教程的主角，这个框架就叫做TSRPC

关于专栏

关于see how是什么，说来很巧，这也是TSRPC作者王大大对我的seho这个名字的猜测，其实我的一个名字也没那么多深意，然后被大佬解读成了see how，所以我感觉这是一个不错的idea，那么本来就是想要出一个tsrpc的系列教程，和大家一起学习这个优秀的框架，就正好作为see how 专栏的第一篇文章吧。

关于TSRPC

在正文开始之前，我希望大家可以去自行先去简单快速的浏览相关知识，tsrpc是一个ts的开源rpc框架，它是为了全栈项目而生的，从我上手的第一天开始，我就对这个框架有了以下的第一印象:

天然二进制传输
纯粹的ts，规避了极大部分开发中的错误
强大的运行时复杂检测
这种前后端开发模式，我闻所未闻

官方文档
视频教程

前期准备

学习tsrpc需要你有一些前置知识和其他准备:

熟悉typescript基本语法
准备一个mongodb数据库

开发

使用tsrpc开发全栈应用简单到没朋友，可以从官方提供的cli快速创建前后端一体项目:

npx create-tsrpc-app@latest

按照指引选择浏览器应用，等待完成安装之后，你的目录中会出现2个目录:

- backend 后端
- frontend 前端

我们直接一睹为快，在前端项目根目录运行

官方的脚手架为我们准备了一个简单的todolist应用

整个前后端的目录结构（摘抄官网）

|- backend --------------------------- 后端项目|- src|- shared -------------------- 前后端共享代码（同步至前端）|- protocols ------------- 协议定义|- api ----------------------- API 实现index.ts|- frontend -------------------------- 前端项目|- src|- shared -------------------- 前后端共享代码（只读）|- protocols|- index.ts

诶，你可能会疑问了，为啥会有一个莫名其妙的shared目录，还要给前端项目去分享这个目录。是因为在shared这个目录我们要定义协议，啥玩意是协议呢？我们通过一个小小的接口来给大家解释什么是协议；


export interface ReqAddPost {newPost: {name: string;};
}export interface ResAddPost {insertedId: string;
}

我们可以在shared/protocols中新建了一个文件PtlAddPost.ts，我们必须以Ptl进行开头定义协议，协议是用来描述一个接口的请求和响应的结构体的文件，你可以这么理解。协议文件通过shared目录共享到前端，你知道会发生什么事情吗？造成了我们前端在对接口的时候，全程代码提示以及严格和请求和返回类型校验。

那么我们接着后端继续聊，协议定义之后该如何做呢？

npm run proto 每当协议更改后，需要重新运行这个命令

tsrpc的设计是协议和api分离，我们必须要清楚，api在我的认知里就是一个异步函数，tsrpc可以帮助我们根据我们刚刚写的协议生成api，比如刚刚我们实现的PtlAddPost.ts，我们运行

在api目录中会多出一个ApiAddPost.ts

import { ApiCall } from "tsrpc";
import { ReqAddPost, ResAddPost } from "../shared/protocols/PtlAddPost";export async function ApiAddPost(call: ApiCall<ReqAddPost, ResAddPost>) {}

我们通过call这个方法获取请求参数以及响应给客户端一些信息，我们来一个简单的例子:

export async function ApiAddPost(call: ApiCall<ReqAddPost, ResAddPost>) {if(call.req.newpost.name){call.success({msg: "hello," + call.req.newpost.name})}else{call.error('Invalid name');}
}

我们的第一个api已经写完了，我们需要正常的过一次test，然后我们在让前端去调用。

tsrpc使用的是mocha这个测试框架。


import { HttpClient } from "tsrpc";
import { serviceProto } from "../../src/shared/protocols/serviceProto";describe("api 测试", async function () {let client = new HttpClient(serviceProto, {server: "http://127.0.0.1:3000",logger: console,});let ret = await client.callApi("AddTest", {newPost: {name: "seho"},});
});

这是我们后端的一个简单的测试用例，在运行这个测试用例之前，您必须要开启后端的服务:

然后可以再开启一个窗口运行npm run test，如果一切正常，你可以看到下面的控制台输出:

粗略计算了一下，我们从开始定义协议到api测试完成，一个简单的接口不到5分钟就已经完成。

这个时候我们可以把这个接口放到前端再继续测试一下。

当然在此之前，我们需要运行以下命令:

我们之前提到过，前后端有一个共享的目录，运行此命令我们就可以把协议等信息同步过来，这个时候我们可以在前端的index.ts文件中，可以获得非常完善的代码提示。


import { HttpClient } from "tsrpc-browser";
import { serviceProto } from "./shared/protocols/serviceProto";let client = new HttpClient(serviceProto, {server: "http://127.0.0.1:3000",logger: console,
});client.callApi("AddTest", {newPost: {name: "hello, seho"},
});

当我们回到浏览器前端页面上时，这个请求就会发出，如果你仔细观察控制台，会看到以下的场景:

我们的请求体被二进制序列化了，这也是tsrpc的特点之一，我们会在稍后的段落中对tsrpc各个特性做介绍，但是此时此刻我们已经完成了一个api的后端开发->test测试->前端调用。

完善我们的程序

上一个部分相信大家已经学会了如何使用tsrpc开发第一个api，这个部分结合了tsrpc的视频教程中的案例，我们需要做一个简单的CRUD，使用mongoDB。

我们需要在本地启动我们的mongoDB服务，然后我们需要添加一些代码到后端backend项目中。

代码开始之前，我们需要安装mongoDB的依赖，我们可以更方便的引入类型定义以及各种数据库方法。

为了和视频教程统一，我们的工具类/架构方式，将直接挪用视频教程中的代码:

写一个数据库的表模型，名为Post.ts


export interface Post {_id: string;author: string;title: string;content: string;visitedNum: number;create: {uid: string;time: Date;};update?: {uid: string;time: Date;};
}

我们的数据库模型是需要共享到前端的，方便前端工程能够复用，但是为了确保后端的类型安全，我们需要在模型上多做一层处理。mongodb的id属性不是string，而是ObjectID，所以我们需要在后端对模型进行类型重写（只重写id字段）。

关于为什么要在后端多做一层封装是因为不可能在前端引入mongodb中的objectID


import { ObjectID } from "mongodb";
import { Overwrite } from "tsrpc";
import { Post } from "../Post";export type DbPost = Overwrite<Post, {_id: ObjectID
}>

我们使用tsrpc提供的Overwrite泛型对刚刚写的Post类型进行改写，将mongodb中的objectID类型引入进来进行替换，然后我们后端工程就要使用这个Dbpost类型，而不是刚刚我们写的Post类型。

数据库相关配置


export const BackConfig = {mongoDb: "mongodb://localhost:27017/test",
};

定义数据库初始化类

import { Collection, Db, MongoClient } from "mongodb";
import { Logger } from "tsrpc";
import { BackConfig } from "./BackConfig";
import { DbPost } from "./dbItems/DbPost";export class Global {static db: Db;static async init(logger?: Logger) {logger?.log(`Start connecting db...`);const client = await new MongoClient(BackConfig.mongoDb).connect();logger?.log(`Db connected successfully...`);this.db = client.db();}static collection<T extends keyof DbCollectionType>(col: T): Collection<DbCollectionType[T]> {return this.db.collection(col);}
}export interface DbCollectionType {Post: DbPost;
}

改写后端index.ts


import { Global } from "../src/shared/protocols/models/Global";async function main() {await server.autoImplementApi(path.resolve(__dirname, 'api'));await Global.init(server.logger);await server.start();
};

ok,截止到目前,我们把第一张表的相关配置已经搞定了,请确保数据库已打开且配置正确，然后我们直接运行一下服务器:

如果你运气好（狗头），那么你应该是成功开启这个服务器，并且控制台能看到连接成功的信息:

然后我们快速开发一下新增API，其他的更新和删除API，希望能大家举一反三，自行开发。


import { Post } from "./models/Post";export interface ReqAddPost {newPost: Omit<Post, "_id" | "create" | "update" | "visitedNum">;
}export interface ResAddPost {insertedId: string;
}

我们规定的请求类型是只能让客户端传递除了id，create，update，visitedNum的Post类型。然后我们还是运行那几个熟悉的命令:

npm run proto
npm run apiimport { ApiCall } from "tsrpc";
import { Global } from "../shared/protocols/models/Global";
import { ReqAddPost, ResAddPost } from "../shared/protocols/PtlAddPost";export async function ApiAddPost(call: ApiCall<ReqAddPost, ResAddPost>) {let op = await Global.collection("Post").insertOne({...call.req.newPost,create: {uid: "xxx",time: new Date(),},visitedNum: 0,});call.succ({insertedId: op.insertedId.toHexString(),});
}

这一part完成～

如何做到动态类型校验

之前我们就提到过，前端在调用后端的api时候，会给出完整的代码提示，从api名称到api的请求体类型等等，那么这一定程度上杜绝了开发中常见的接口联调不细心的问题。在传统的前后端开发中，尤其是分离模式，有一个非常常见的问题就是动态类型校验。每个语言/框架都有自己类型校验的手段，比如springmvc我们可以通过注解的方式来校验(下面展示了控制器中的校验，还有其他校验手段):

@Controller
@RequestMapping("valid")
@Slf4j
public class ValidateController {private static final String BASE_PATH = "/valid/";@RequestMapping("index")public String index(@Validated() Student student,BindingResult result){ return BASE_PATH + "index";}
}

那么tsrpc是如何保证数据传输的正确性的呢，首先我们如果在前端使用tsrpc的浏览器请求包，我们调用api时候不仅会在开发中提示开发者这个字段是错误的，而且会在请求发出之前做前端方面的遏制。在后端请求到达异步函数之前，也会去做第三次校验；所以我们在后端异步函数中使用到的参数一定是类型安全，完全不需要担心安全问题。

市面上有很多js领域解决动态校验的方案；最常见应该就是json schema，可以基于json自己实现一套校验方法可以在运行时来做校验。但是仍然有很多缺点，比如不能在前端进行运行时提示且可能重复写很多类型定义。那么tsrpc核心中使用到了一个库（这个库也是同个作者开发的）:

tsrpc-buffer

为了实现ts动态类型校验，不可能把整个ts加进去，因为那有足足60m多，这是不现实的。所以作者开发了这个库。tsrpc依赖了这个库，它对ts的语法进行了兼容，目前支持了大部分的ts的写法，包括我们常用的string，number等，还支持一些复杂的泛形。

如果你想细细了解这方面，可以看一下文档支持的ts类型有哪些

当然，随着ts的更新，这个buffer也会支持更多的ts类型，可以做更完善的全栈应用。而且我们可以使用tsrpc进行原汁原味的ts开发，市面上的第三方工具/框架需要借助另外编程语言/DSL，tsrpc-buffer完全让你使用ts，你不会感觉到一丝违和感。

二进制序列化

tsrpc的二进制序列化机制是由我们上文中提到的tsrpc-buffer中实现的，那么这个特性带给我们的是比json更小的传输体积且支持更多的数据类型，ArrayBuffer, Date等。这意味着使用tsrpc的全栈应用在应对上传图片这种业务的时候简直就像是小儿科，我们可以用一个例子来证明。

export interface ReqUpload {fileName: string,fileData: Uint8Array
}export interface ResUpload {url: string;
}

我们通过刚刚学到的一些命令，来生成协议以及api

npm run proto
npm run apiimport { ApiCall } from "tsrpc";
import { ReqUpload, ResUpload } from "../shared/protocols/PtlUpload";
import fs from "fs/promises";export async function ApiUpload(call: ApiCall<ReqUpload, ResUpload>) {await fs.writeFile("uploads/" + call.req.fileName, call.req.fileData);call.succ({url: "http://127.0.0.1:3000/uploads/" + call.req.fileName,});
}

为了让前端调用，同步shared下的协议

写一个简单的file选择器在index.html中

<input type="file" id="fileInput">import { HttpClient } from "tsrpc-browser";
import { serviceProto } from "./shared/protocols/serviceProto";let client = new HttpClient(serviceProto, {server: "http://127.0.0.1:3000",logger: console,
});const input = document.getElementById("fileInput") as HTMLInputElement;input.addEventListener("change", async () => {if (input.files) {const fileData = await loadFile(input.files?.[0]);upload(fileData, input.files?.[0].name);}
});const upload = async (fileData: Uint8Array, fileName: string) => {const fr = new FileReader();client.callApi("Upload", {fileData,fileName,});
};function loadFile(file: File): Promise<Uint8Array> {return new Promise((rs) => {let reader = new FileReader();reader.onload = (e) => {rs(new Uint8Array(e.target!.result as ArrayBuffer));};reader.readAsArrayBuffer(file);});
}

开发完毕，我们可以仔细看一下控制台:

尽管我们在日常开发中会用到一些组件库，组件库帮助我们做了上传的大部分工作，所以我们写原生的上传可能在代码量上更多，但是省去了前后端转换Formdata的时间。

向后兼容http(json)和WebSocket

tsrpc也向后支持json，我们可以在客户端进行一个简单的配置，发送的请求就是json啦:

let client = new HttpClient(serviceProto, {server: "http://127.0.0.1:3000",json: true,logger: console,
});

我其实暂时没有想到非要使用json的场景，使用二进制序列化比json体积更小传输更快，本地开发的日志也在控制台随时打印，所以我还是建议大家使用默认的二进制序列化的传输模式。

tsrpc设计之初是为了游戏，因为传输特性能让websocket更高效，我们可以用tsrpc简单做一个websocket-demo，具体实现我参考了官网的实现，如果你想直接了解官网的这一part的内容，直接移步:

websocket实时服务-tsrpc

tsrpc的实现和协议无关，意味着咱们之前写的代码都可以用，仅仅做一个简单的调整替换即可。

websocket的消息是tsrpc传输中最小单元，我们需要用另外一个方法去定义协议，我们的websocket例子如下:

客户端发起一个请求，服务端接收并且向所有客户端发送一个消息

首先我们需要定义一个MsgHello.ts这样的协议:


export interface MsgHello {time: Date;content: string;
}

这个协议规定了前后端通讯的请求体。

我们需要改写后端backend中的index.ts，将原先的HTTP服务，改成Websocket服务

import { HttpServer, WsServer } from "tsrpc";export const server = new WsServer(serviceProto, {port: 3000,logMsg: true
});

这里导出server是有用意的，我们将在之后的代码中会用到这个server。

改写frontend前端中的index.ts

import { HttpClient, WsClient } from "tsrpc-browser";let ws = new WsClient(serviceProto, {server: "ws://127.0.0.1:3000",logger: console,
});const init = async () => {let result = await ws.connect();
};init();

我们需要一个api来触发后端给client发送websocket消息:


export interface ReqSend {content: string;
}export interface ResSend {time: Date;
}

定义成功后，我们运行以下几个命令:

npm run proto
npm run api

运行成功，我们可以在api文件夹下的ApiSend.ts中写入以下内容：

import { ApiCall } from "tsrpc";import { server } from "..";
import { ReqSend, ResSend } from "../shared/protocols/PtlSend";export async function ApiSend(call: ApiCall<ReqSend, ResSend>) {const time = new Date();call.succ({time,});server.broadcastMsg("Hello", {content: call.req.content,time,});
}

我们的后端逻辑写完了，我们运行以下命令，将协议同步到前端

我们进一步改写前端frontend/src/index.ts:

import { HttpClient, WsClient } from "tsrpc-browser";
import { serviceProto } from "./shared/protocols/serviceProto";let ws = new WsClient(serviceProto, {server: "ws://127.0.0.1:3000",logger: console,
});const init = async () => {let result = await ws.connect();console.log(result)if (result.isSucc) {// ws.callApiws.callApi("Send", {content: "hello websocket",});}
};init();

我们在页面初始化的时候，向后端发送刚刚写好的SendApi，这个时候我们既能收到api的返回，也能收到websocket的消息推送。

可以看到websocket传输也是二进制的，我们在开发中，也能发现，无论是callApi和发送websocket通知，从始至终都有类型推导，永远不会在传输中出现类型上的错误，这就是tsrpc的强大之处。

多平台

tsrpc支持多个平台，支持浏览器/小程序/原生ios 安卓/nodejs，甚至它还支持serverless，可以使用tsrpc开发基于阿里云/腾讯云的云函数；在后续我也会对tsrpc生态开发更多插件，使其兼容uniapp&unicloud，让他严格严格意义上跨多端，我相信tsrpc可以改变unicloud的开发习惯，让全栈应用更简单。

结语

本篇文章所有的知识点均在官网&视频教程有体现，视频教程在文章开始之前就有链接，非常希望大家能够先去看一下那个视频。tsrpc的教程还会出，下一篇关于tsrpc文章主要还是讲一下如何和serverless（unicloud）融合。这篇文章正在写大纲，相信也会在这个月之内能和大家见到。

本文使用文章同步助手同步