docs: add document for esm version (#3166)

* docs: add release 3.12

* docs: add 3.12.0 release

* docs: up typo

* docs: add esm

* docs: add api

* docs: add ctx.forward

site/blog/2023-08-13-remove-node-14-ci.md

@@ -0,0 +1,18 @@
+---
+slug: remove-node-14-ci
+title: 移除 Node.js v14 的 CI 环境
+authors: [harry]
+tags: [node]
+
+
+---
+
+最近一段时间，我们发现越来越多的库移除了 Node.js v14 的支持。
+
+有些库是升级的大版本，有些库仅仅只升级 minor 版本，这使得依赖他们的业务、模块乃至框架都很难信任社区的 SemVer 版本约定了。
+
+为了保持 Midway 的单测正常运行，从 v3.12.0 开始，Midway 移除了 Node.js v14 的 CI，这意味着我们无法测试 Node.js v16 以下社区库的兼容性，只能靠社区库更新的 Changelog 以及我们的经验来保证。
+
+如果我们发现某些库只支持特定版本的 Node.js，我们会在 `package.json` 中进行版本限制，如果你发现某些库的版本更新无法在低版本 Node.js 中运行，且 Midway 的组件没有进行限制，请通知我们。
+
+最后再次提醒，如果没有强需求，请使用 Node.js v16 以上版本。

site/blog/2023-08-14-release-3.12.md

@@ -0,0 +1,61 @@
+---
+slug: release/3.12.0
+title: Release 3.12.0
+authors: [harry]
+tags: [release]
+
+
+
+
+---
+
+升级请参考  [如何更新 Midway](/docs/how_to_update_midway) 中描述，请不要单独升级某个组件包。
+
+在经过了几个月的努力更新之后，Midway 迎来了 3.12 版本，这是一个改动比较大的版本。
+
+
+
+## Breaking
+
+从 v3.12.0 开始，Midway 移除了 Node.js v14 的 CI，原因请参考 [这里](/blog/remove-node-14-ci)。
+
+
+
+## Features
+
+### 1、ESM 的支持
+
+从 v3.12.0 开始，midway 支持创建 ESModule 项目，使用时和传统 CJS 项目会有所不同，由于时间紧迫，我们没有针对所有的组件进行测试，如有兼容性问题，请提交 issue。
+
+此外，由于原有的工具体系已经无法很好的兼容 ESM 环境，为了减少维护成本，我们启用了一套全新的工具链，后续普通 CJS 项目也会统一到这一套上来。
+
+更多细节请查看 [ESM 文档](/docs/esm)。
+
+
+
+### 2、FaaS 架构变更
+
+从 v3.12.0 开始，Midway FaaS 使用全新的一套架构支持现有的 Serverless 平台，这一部分后续将会在文档中体现。
+
+
+
+## 其他的一些变化
+
+
+
+- 1、添加了 `ctx.getApp()` 方法，可以从 ctx 拿到自己 app，打通了整条从 framework，到 app 和 ctx 的链路
+
+- 2、core 中的 httpClient 现在支持了所有的 http method
+
+- 3、增加了一个内部跳转 URL 的 api，`ctx.forward`
+
+- 4、IoC 容器增加了一个获取对象作用域的 API，`container.getInstanceScope(xxx)`
+
+
+
+
+
+## 依赖更新
+
+
+具体可以查看 [Changelog](https://midwayjs.org/changelog/v3.12.0)。

site/docs/container.md

@@ -433,6 +433,45 @@ export class ReportMiddleware implements IMiddleware<Context, NextFunction> {
 ```
 
 
+
+### 获取对象作用域
+
+从 v3.12.0 版本开始，依赖注入容器增加了一个新的获取对象作用域的 API。
+
+```typescript
+import { Controller, Inject, ApplicationContext, Get, IMidwayContainer } from '@midwayjs/core';
+import { UserService} from '../service/user.service';
+
+@Singleton()
+export class UserSerivce {
+  // ...
+}
+
+@Controller('/')
+export class HomeController {
+  @Inject()
+  userService: UserService;
+
+  @ApplicationContext()
+  applicationContext: IMidwayContainer;
+
+  @Get('/')
+  async home(): Promise<string> {
+    console.log(this.applicationContext.getInstanceScope(this));
+    // => Request
+
+    console.log(this.applicationContext.getInstanceScope(this.userService));
+    // => Singleton
+
+    // ...
+  }
+}
+```
+
+`getInstanceScope` 方法的返回值为 `ScopeEnum` 值。
+
+
+
 ## 注入规则
 
 Midway 支持多种方式的注入。

site/docs/controller.md

@@ -947,6 +947,44 @@ export class HomeController {
 
 
 
+## 内部重定向
+
+从 v3.12.0 开始，框架提供了一个内部重定向 API `ctx.forward(url)`，仅支持 koa/egg 类型。 
+
+和外部重定向不同的地方在于，内部重定向不会修改浏览器的 URL，只在程序内部流转。
+
+```typescript
+import { Controller, Get, Inject } from '@midwayjs/core';
+
+@Controller('/')
+export class HomeController {
+  @Inject()
+  ctx: Context;
+
+  @Get('/')
+  async home() {
+    return this.ctx.forward('/api');
+  }
+
+  @Get('/api')
+  async api() {
+    return 'abc';
+  }
+}
+```
+
+注意，内部重定向有一些规则：
+
+* 1、重定向会保留原始路由的所有参数，即透传整个 ctx
+
+* 2、重定向只能在相同的 http method 中进行
+
+* 3、重定向不会再执行一遍 Web Middleware，不会执行守卫，但是会执行拦截器和参数装饰器
+
+
+
+
+
 ## 全局路由前缀
 
 需要在 `src/config/config.default` 配置中设置。

site/docs/esm.md

@@ -2,87 +2,105 @@
 
 在过去的几年中，Node.js一直致力于支持运行 ECMAScript模块 (ESM)。这是一个很难支持的功能，因为 Node.js 生态系统的基础是建立在一个不同的模块系统，称为 CommonJS (CJS)。
 
-两个模块系统之间的互操作带来了巨大的挑战，并具有许多新功能。但是，现在在Node.js中实现了对 ESM 的支持，并且尘埃落定。
+两个模块系统之间的互操作带来了巨大的挑战，并具有许多功能差异。
 
-在此基础上，Midway 也支持了 ESM 格式的文件加载，业务也可以使用这种全新的模块加载方式来构建自己的业务。
+自 Node.js v16 之后，ESM 的支持相对已经稳定，TypeScript 的一些配合功能也相继落地。
+
+在此基础上，Midway 支持了 ESM 格式的文件加载，业务也可以使用这种全新的模块加载方式来构建自己的业务。
+
+:::caution
+
+在没有了解 ESM 前，不建议用户使用。
+
+:::
+
+推荐阅读：
+
+* [TypeScript 官方 ESM 指南](https://www.typescriptlang.org/docs/handbook/esm-node.html)
+* [Node.js 官方 ESM 文档](https://nodejs.org/api/esm.html)
 
 
 
 ## 脚手架
 
 由于改动较多，Midway 提供了全新的 ESM 格式的脚手架，如有 ESM 的需求，我们推荐用户重新创建后再来开发业务。
 
+```bash
+$ npm init midway
+```
+
+选择 esm 分组中的脚手架。
+
 
 
-## 配置方式
+## 和 CJS 项目的差异
 
-### package.json 的变化
+### 1、package.json 的变化
 
  `package.json` 中的 type 必须设置为 `module`。
 
 ```json
 {
   "name": "my-package",
   "type": "module",
-  "//": "...",
+  // ...
   "dependencies": {
   }
 }
 ```
 
 
 
-### tsconfig.json 中的变化
+### 2、tsconfig.json 中的变化
 
 `compilerOptions` 编译相关的选项需要设置为 `Node16` 或者 `NodeNext`。
 
 ```json
 {
   "compilerOptions": {
-    "target": "NodeNext",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Node16",
+    "esModuleInterop": true,
     // ...
   }
 }
 ```
 
 
 
-### jest.config.js 的变化
-
-```javascript
-module.exports = {
-  roots: ['<rootDir>/scripts'],
-  testMatch: ['**/*.test.ts'],
-  extensionsToTreatAsEsm: ['.ts'],
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1',
-  },
-  transform: {
-    '^.+\\.tsx?$': [
-      'ts-jest',
-      {
-        useESM: true,
-      },
-    ],
-  },
-}
-```
+### 3、工具链的变化
 
+由于原有开发工具链仅支持 CJS 代码，且社区的部分模块并没有做好 ESM 的支持，Midway 在 ESM 模式下，使用新的工具链。
 
+* 开发命令，使用 mwtsc （仅做了 tsc 必要的包裹）
+* 测试和覆盖率命令，使用 mocha + ts-node，同时测试代码和测试的配置都有所调整
+* 构建命令，使用 tsc
 
-## 一些变化
+一些不再支持的功能
 
-1、ts 中，import 的文件必须指定后缀名，且后缀名为 js
+* alias path，请用 Node.js 自带的 [子路径导出](https://nodejs.org/api/packages.html#subpath-exports) 代替
+* 构建时非 js 文件的拷贝，将非代码文件放到 src 外部，或者在 build 时添加自定义命令
+
+具体差异可以参考 [脚手架](https://github.com/midwayjs/midway-boilerplate/blob/master/v3/midway-framework-koa-esm/boilerplate/_package.json) 进行核对。
+
+
+
+### 4、一些代码差异
+
+下面快速列出一些开发中 ESM 和 CJS 的差异。
+
+
+
+1、ts 中，import 的文件必须指定后缀名，且后缀名为 js。
 
 ```typescript
 import { helper } from "./foo.js"; // works in ESM & CJS
 ```
 
 
 
-2、你不能再使用 `module.exports` 或者 `exports.` 来导出
+2、你不能再使用 `module.exports` 或者 `exports.` 来导出。
 
 ```typescript
 // ./foo.ts
@@ -101,9 +119,25 @@ import { helper } from "./foo"; // only works in CJS
 
 
 
+4、你不能在代码中使用 `__dirname`，`__filename` 等和路径相关关键字
 
+所以配置的部分，必须使用对象模式。
 
-## 一些资料
+```typescript
+import { Configuration } from '@midwayjs/core';
+import DefulatConfig from './config/config.default.js';
+import UnittestConfig from './config/config.unittest.js';
+
+@Configuration({
+  importConfigs: [
+    {
+      default: DefulatConfig,
+      unittest: UnittestConfig,
+    },
+  ],
+})
+export class MainConfiguration {
+  // ...
+}
+```
 
-- https://www.typescriptlang.org/docs/handbook/esm-node.html
-- https://japanese-document.github.io/tips/2022/typescript-ts-node-esmodules.html

site/docs/req_res_app.md

@@ -432,3 +432,14 @@ this.ctx.getLogger('custom');
 // => custom logger
 ```
 
+
+
+### getApp
+
+从 ctx 上获取当前框架类型的 app 对象。
+
+```typescript
+const app = this.ctx.getApp();
+// app.getConfig();
+```
+