Zonetk-core NPM

zonetk-core zontk框架核心代码

基于koa typescript实现的快速开发框架

快速上手

1.安装zonetk-cli工具

npm install zonetk-cli -g

2.创建第一个项目

zonetk create --name zonetk-demo

3.目录介绍

├── README.md
├── config                                        ----配置文件目录
│   └── default.js
├── ormconfig.js
├── package.json
├── dist                                          ----编译后目录
├── src                                           ----源代码目录
│   ├── controller                                ----controller目录
│   │   └── user.controller.ts
│   ├── entity                                    ----orm实体类目录
│   │   └── user.ts
│   ├── index.ts                                  ----程序入口
│   ├── lib                                       ----第三方扩展，自由定义
│   │   └── databaseLog.lib.ts
│   ├── middleware                                ----中间件目录
│   │   ├── errorHandle.middleware.ts
│   │   └── requestLog.middleware.ts
│   ├── migration                                 ----数据库迁移文件目录
│   │   └── 1564975664486-UserCreateMigration.ts
│   ├── plugin                                    ----插件目录，存放单一全局实例
│   │   └── redis.plugin.ts
│   ├── service                                   ----实体类数据库查询业务
│   │   └── user.service.ts
│   └── transformer                               ----api接口返回数据格式化工具目录
│   │    └── user.transformer.ts
│   ├── schedule                                  ----定时任务目录
│   │   └── first.schedule.ts
│   └── rpc                                       ----rpc方法目录
│   │    └── first.rpc.ts
└── tsconfig.json

我们会发现常见的代码都会存放于 /src 目录下，由于 ts 的特殊性，在服务器上会通过打包构建为 *.js 文件存放于 /dist 目录。将源文件和编译后文件分开是我们最开始的初衷。

4.快速开发引导

想要快速上手 zonetk，除了需要了解一些基础的东西：

虽然可以直接用 js 的语法书写，但是你最好了解 TypeScript，这里有个快速介绍。
尽可能使用面向对象的思想来编码，它的经久不衰是有道理的，使用 class 机制能够方便的融入我们的新特性。了解 zonetk 的依赖注入体系，以及常用的装饰器，这里做了依赖注入的介绍。

功能介绍

1.TypeORM

TypeORM 是一个ORM框架，它可以运行在 NodeJS、Browser、Cordova、PhoneGap、Ionic、React Native、Expo 和 Electron 平台上，可以与 TypeScript 和 JavaScript (ES5,ES6,ES7,ES8)一起使用。它的目标是始终支持最新的 JavaScript 特性并提供额外的特性以帮助你开发任何使用数据库的（不管是只有几张表的小型应用还是拥有多数据库的大型企业应用）应用程序。

不同于现有的所有其他 JavaScript ORM 框架，TypeORM 支持 Active Record 和 Data Mapper 模式，这意味着你可以以最高效的方式编写高质量的、松耦合的、可扩展的、可维护的应用程序。

TypeORM 参考了很多其他优秀 ORM 的实现, 比如 Hibernate, Doctrine 和 Entity Framework。

TypeORM 的一些特性:

支持 DataMapper 和 ActiveRecord (随你选择)
实体和列
数据库特性列类型
实体管理
存储库和自定义存储库
清晰的对象关系模型
关联（关系）
贪婪和延迟关系
单向的，双向的和自引用的关系
支持多重继承模式
级联
索引
事务
迁移和自动迁移
连接池
主从复制
使用多个数据库连接
使用多个数据库类型
跨数据库和跨模式查询
优雅的语法，灵活而强大的 QueryBuilder
左联接和内联接
使用联查查询的适当分页
查询缓存
原始结果流
日志
监听者和订阅者（钩子）
支持闭包表模式
在模型或者分离的配置文件中声明模式
json / xml / yml / env 格式的连接配置
支持 MySQL / MariaDB / Postgres / SQLite / Microsoft SQL Server / Oracle / sql.js
支持 MongoDB NoSQL 数据库
可在 NodeJS / 浏览器 / Ionic / Cordova / React Native / Expo / Electron 平台上使用
支持 TypeScript 和 JavaScript
生成高性能、灵活、清晰和可维护的代码
遵循所有可能的最佳实践
命令行工具

详细使用请参考文档

2.路由和控制器

zonetk 使用 koa-router 作为路由的承载者，同时在 ts 的语法上做了一些简化，我们将路由和控制器放在了一起，使用装饰器来标注路由。

由于 zonetk 采用了 IoC 自扫描机制，使得在一定程度上弱化了目录结构约定，通过装饰器的机制，可以非常方便的进行解耦，按业务逻辑拆分等。

现在可以在任意目录下创建 controller，不再限定 app/controller 目录，同理，其他装饰器也不限定。

现在可以做到比如 src/web/controller 下放 controller，也可以按业务维度分，比如 user 目录，包含跟用户相关所有的 controller/service/dao 等，对微服务或者 serverless 比较友好。

快速创建控制器我们可以使用脚手架工具:

zonetk create:controller --name user

路由装饰器

我们的控制器目录为 src/controller ，我们在其中编写 *.ts 文件。例如下面的 userController.controller.ts ，我们提供了一个获取用户的接口。

import { provide, controller, inject, Http } from 'zonetk-core';

@provide()
@controller('/user')
export class UserController {

  @inject('userService')
  service: IUserService;

  @Http.get('/:id')
  async getUser(ctx): Promise<void> {
    const id: number = ctx.params.id;
    const user: IUserResult = await this.service.getUser({id});
    ctx.body = {success: true, message: 'OK', data: user};
  }
}

我们创建了 @controller 装饰器用来定义这个类为 Controller，同时，提供了方法装饰器用于标注请求的类型。 @controller 的参数为字符串 pattern，我们会将这个值传入 router.prefix(prefix) 的参数中。
zontk 针对 web 请求，提供了和 koa-router 对应的方法装饰器，列表如下。

@Http.get
@Http.post
@Http.del
@Http.put
@Http.patch
@Http.options
@Http.head
@Http.all

这几个装饰器用于修饰不同的异步方法，同时对应到了 koa-router 的相应的方法。和原有提供的控制器一样，每个控制器都为异步方法，参数为 koa 上下文。

路由优先级

在单页应用下，经常会出现 /* 这种路由，在原本的路由文件中，我们可以通过调整代码的顺序，来使的路由的匹配顺序发生变化。而由于使用了装饰器的关系，在新的体系无法控制文件扫描和加载顺序，这就使得路由匹配的顺序不可控。

zonetk 提供了 @priority(priority: number) 装饰器，用于修饰 class，定义路由的优先级，默认的路由优先级为 0，可以设置负数让优先级降低。

@provide()
@priority(-1)
@controller('/')
export class HomeController {

  @Http.get('/hello')
  async index(ctx) {
    ctx.body = 'hello';
  }

  @Http.get('/*')
  async all(ctx) {
    ctx.body = 'world';
  }
}

路由中间件

现在可以提供一个 middleware（任意目录），比如 src/middleware/api.ts。

import { Middleware, WebMiddleware, provide,config,BaseMiddleware } from 'zonetk-core';

@provide()
export class ApiMiddleware extends BaseMiddleware implements WebMiddleware {

  @config('hello')
  helloConfig;

  resolve(): Middleware {
    return async (ctx, next) => {
      ctx.api = '222' + this.helloConfig.b;
      await next();
    };
  }

}

由于是 class，依旧可以使用 inject/plugin/config 等装饰器修饰。

@provide()
@controller('/', {middleware: ['homeMiddleware']})
export class My {

  @inject()
  ctx;

  @Http.get('/', {middleware: ['apiMiddleware']})
  async index() {
    this.ctx.body = this.ctx.home + this.ctx.api;
  }
}

在 @controller 和 @get/post 等路由装饰器上都提供了 middleware 参数。
这里的 middleware 参数是一个数组，可以传多个字符串或者 koa middleware，如果是字符串，会从 IoC 容器中获取对应的 WebMiddleware 接口实例的 resolve 方法的结果。由于中间件在生命周期的特殊性，会在应用请求前就被加载（绑定）到路由上，所以无法和上下文关联。

中间件类固定为单例（Singleton），所有注入的内容都为单例，包括但不限于 @config/@logger/@plugin 等。

这意味着你可以注入一个 service，但是这个 service 中无法注入 ctx 属性。

这个时候，你必须在 resolve 方法中，通过调用 ctx.requestContext.getAsync('xxx') 的方式来创建请求作用域实例，和上下文绑定。

@provide()
export class ApiMiddleware extends BaseMiddleware implements WebMiddleware {

  @inject()
  myService;  // 由于中间件实例属于单例，这个实例即使注入也无法获取到 ctx

  resolve(): Middleware {
    return async (ctx, next) => {
      // 必须通过从请求作用域中获取对象的方式，来绑定上下文
      ctx.service = await ctx.requestContext.getAsync('myService');
      await next();
    };
  }

}

一个方法挂载多个路由

@provide()
@controller('/', {middleware: ['homeMiddleware']})
export class My {

  @inject()
  ctx;

  @Http.get('/', {middleware: ['apiMiddleware']})
  @Http.post('/api/data')
  async index() {
    this.ctx.body = this.ctx.home + (this.ctx.api || '');
  }
}

这样请求进来， post 和 get 拿到的结果是不一样的（get请求挂载了额外的中间件）。

快速创建中间件我们可以使用脚手架工具:

zonetk create:middleware --name api

3.框架增强注入

注入插件

定义一个插件

import { BasePlugin, ZonetkPlugin, config } from "zonetk-core";
import * as IoRedis from "ioredis";
import * as _ from "lodash";

export default class RedisPlugin extends BasePlugin implements ZonetkPlugin<IoRedis.Redis | IoRedis.Cluster>{

  @config("redis")
  redisConfig

  private redis: IoRedis.Redis | IoRedis.Cluster;
  constructor() {
    super()
    if (!this.redisConfig) {
      throw new Error("redis has no config")
    }
    this.redisConfig = this.redisConfig.split(",")
    if (this.redisConfig.length > 1) {
      this.redis = new IoRedis.Cluster(this.redisConfig)
    } else {
      this.redis = new IoRedis(this.redisConfig[0]);
    }
  }
  resolve() {
    return this.redis;
  }
}

通过装饰器@plugin在控制器中注入插件并使用

import { provide, inject, controller, Http, BaseController, plugin } from "zonetk-core"

@provide()
export default class UserController extends BaseController {
  @plugin("redis")
  redis

  @Http.get("/userInfo")
  async getUserInfo(){
    const {userId} = this.ctx.query
    const cacheUser = await this.redis.get(`userDetail:${userId}`)
  }
}

注入配置

使用@config装饰器的方式读取配置文件到类属性上。下面例子是读取redis的连接配置

import { BasePlugin, ZonetkPlugin, config } from "zonetk-core";
import * as IoRedis from "ioredis";
import * as _ from "lodash";

export default class RedisPlugin extends BasePlugin implements ZonetkPlugin<IoRedis.Redis | IoRedis.Cluster>{

  @config("redis")
  redisConfig

  private redis: IoRedis.Redis | IoRedis.Cluster;
  constructor() {
    super()
    if (!this.redisConfig) {
      throw new Error("redis has no config")
    }
    this.redisConfig = this.redisConfig.split(",")
    if (this.redisConfig.length > 1) {
      this.redis = new IoRedis.Cluster(this.redisConfig)
    } else {
      this.redis = new IoRedis(this.redisConfig[0]);
    }
  }
  resolve() {
    return this.redis;
  }
}