docs: update axios and health manager

midwayjs · Mar 15, 2024 · 1bce6bb · 1bce6bb
1 parent 16003dc
commit 1bce6bb
Show file tree

Hide file tree

Showing 8 changed files with 100 additions and 36 deletions.
diff --git a/site/docs/built_in_service.md b/site/docs/built_in_service.md
@@ -15,8 +15,7 @@ Midway 内置的应用管理器，可以使用它获取到所有的 Application
 可以通过注入获取，比如对不同的 Application 添加同一个中间件。
 
 ```typescript
-import { MidwayApplicationManager } from '@midwayjs/core'
-import { Configuration, Inject } from '@midwayjs/decorator';
+import { MidwayApplicationManager, onfiguration, Inject } from '@midwayjs/core'
 import { CustomMiddleware } from './middleware/custom.middleware';
 
 @Configuration({
@@ -479,8 +478,7 @@ Midway 内置的路由表服务，用于应用路由和函数的创建。
 可以通过注入获取。
 
 ```typescript
-import { MidwayWebRouterService } from '@midwayjs/core';
-import { Configuration, Inject } from '@midwayjs/decorator';
+import { MidwayWebRouterService, Configuration, Inject } from '@midwayjs/core';
 
 @Configuration({
   // ...
@@ -523,8 +521,7 @@ Midway 内置的函数信息服务，继承与 `MidwayWebRouterService` ，方
 可以通过注入获取。
 
 ```typescript
-import { MidwayServerlessFunctionService } from '@midwayjs/core';
-import { Configuration, Inject } from '@midwayjs/decorator';
+import { MidwayServerlessFunctionService, Configuration, Inject } from '@midwayjs/core';
 
 @Configuration({
   // ...
@@ -565,11 +562,17 @@ API 如下
 
 Midway 内置的健康检查执行服务，用于外部扩展的健康检查能力。
 
+完整的健康检查包含两个部分：
+
+* 1、健康检查的触发端，比如外部的定时请求，通常为一个 Http 接口
+* 2、健康检查的执行端，一般在各个组件或者业务中，检查特定的项是否正常
+
+`MidwayHealthService` 一般用于健康检查的触发端，下面描述的内容一般在触发端会实现。
+
 可以通过注入获取后，执行健康检查任务。
 
 ```typescript
-import { MidwayHealthService } from '@midwayjs/core';
-import { Configuration, Inject } from '@midwayjs/decorator';
+import { MidwayHealthService ,Configuration, Inject } from '@midwayjs/core';
 
 @Configuration({
   // ...
@@ -635,3 +638,4 @@ export default {
 };
 ```
 
+健康检查的执行端在业务或者组件的生命周期中实现，具体请查看 [生命周期](/docs/lifecycle#onhealthcheck)。
diff --git a/site/docs/extensions/axios.md b/site/docs/extensions/axios.md
@@ -416,18 +416,18 @@ export class MainConfiguration {
 }
 ```
 
-### 直接使用Axios
+### 直接使用 Axios
 
 `@midayjs/axios`导出了原始的`axios`实例，在非应用环境中可以直接使用。
 
 ```typescript
-import { axios } from '@midwayjs/axios';
+import { Axios } from '@midwayjs/axios';
 import { ReadStream, createWriteStream } from 'fs';
 import { finished } from 'stream/promises';
 
 async function download(url: string, filename: string) {
   const writer = await createWriteStream(filename);
-  const res = axios.get<ReadStream>(url, {
+  const res = Axios.get<ReadStream>(url, {
     responseType: 'stream',
   });
   res.data.pipe(writer);

diff --git a/site/docs/extensions/koa.md b/site/docs/extensions/koa.md
@@ -17,7 +17,6 @@ Midway 默认的示例都是基于该包。
 
 ```bash
 $ npm i @midwayjs/koa@3 --save
-$ npm i @types/koa --save-dev
 ```
 
 或者在 `package.json` 中增加如下依赖后，重新安装。
@@ -28,10 +27,6 @@ $ npm i @types/koa --save-dev
     "@midwayjs/koa": "^3.0.0",
     // ...
   },
-  "devDependencies": {
-    "@types/koa": "^2.13.4",
-    // ...
-  }
 }
 ```
 
@@ -232,11 +227,11 @@ export default {
 | cert         | string \| Buffer \| Array<Buffer\|Object> | 可选，Https cert，服务端证书                            |
 | ca           | string \| Buffer \| Array<Buffer\|Object> | 可选，Https ca                                          |
 | http2        | boolean                                   | 可选，http2 支持，默认 false                            |
-| proxy        | boolean                                   | 可选，是否开启代理，如果为 true 则对于 request 请求中的 host / protocol / ip分别优先从 Header 字段中 X-Forwarded-Host / X-Forwarded-Proto / X-Forwarded-For 获取，默认 false                            |
+| proxy        | boolean                                   | 可选，是否开启代理，如果为 true 则对于 request 请求中的 ip 优先从 Header 字段中 X-Forwarded-For 获取，默认 false           |
 | subdomainOffset        | number                                   | 可选，子域名的偏移量，默认 2                            |
 | proxyIpHeader        | string                                   | 可选，获取代理 ip 的字段名，默认为 X-Forwarded-For |
 | maxIpsCount        | number                                   | 可选，获取的 ips 最大数量，默认为 0（全部返回）|
-| serverTimeout | number | 可选，服务端超时配置，单位秒。 |
+| serverTimeout | number | 可选，服务端超时配置，默认为 2 * 60 * 1000（2 分钟），单位毫秒 |
 
 
 
@@ -278,6 +273,37 @@ export default {
 
 
 
+### 反向代理配置
+
+如果使用了 Nginx 等反向代理，请开启 `proxy` 配置。
+
+```typescript
+// src/config/config.default
+export default {
+  // ...
+  koa: {
+    proxy: true,
+  },
+}
+```
+
+默认使用 `X-Forwarded-For` Header，如果代理配置不同，请自行配置不同的 Header。
+
+```typescript
+// src/config/config.default
+export default {
+  // ...
+  koa: {
+    proxy: true,
+    proxyIpHeader: 'X-Forwarded-Host'
+  },
+}
+```
+
+
+
+
+
 ### Https 配置
 
 在大多数的情况，请尽可能使用外部代理的方式来完成 Https 的实现，比如 Nginx。

diff --git a/site/docs/release_schedule.md b/site/docs/release_schedule.md
@@ -6,4 +6,5 @@
 | --- | --- | --- | --- | --- | --- |
 | midway v1（inner v6) | **End-of-Life** | 2018-06-14 | 2018-10 | 2020-04 | 2022-04 |
 | midway v2（inner v7) | **Maintenance LTS** | 2020-10 | 2021-02 | 2021-10 | 2024-04 |
-| midway v3（inner v8) | **Active LTS** | 2022-01 | 2022-06 |  |  |
+| midway v3（inner v8) | **Maintenance LTS** | 2022-01 | 2022-06 | 2023-10 |  |
+| midway v4（inner v9) | **Development** |  |  |  | |
diff --git a/site/i18n/en/docusaurus-plugin-content-docs/current/built_in_service.md b/site/i18n/en/docusaurus-plugin-content-docs/current/built_in_service.md
@@ -561,11 +561,17 @@ For more information, see [Web route table](# router_table).
 
 Midway's built-in health check execution service is used for externally extended health check capabilities.
 
+A complete health check consists of two parts:
+
+* 1. The trigger end of the health check, such as an external scheduled request, is usually an Http interface
+* 2. The execution end of the health check usually checks whether specific items are normal in each component or business.
+
+`MidwayHealthService` is generally used as the trigger end of health check. The content described below is generally implemented on the trigger end.
+
 It can be obtained through injection and then perform health check tasks.
 
 ```typescript
-import { MidwayHealthService } from '@midwayjs/core';
-import { Configuration, Inject } from '@midwayjs/decorator';
+import { MidwayHealthService, Configuration, Inject } from '@midwayjs/core';
 
 @Configuration({
   // ...
@@ -630,3 +636,5 @@ export default {
    }
 };
 ```
+
+The execution end of the health check is implemented in the life cycle of the business or component. For details, please see [Life Cycle](/docs/lifecycle#onhealthcheck).
diff --git a/site/i18n/en/docusaurus-plugin-content-docs/current/extensions/axios.md b/site/i18n/en/docusaurus-plugin-content-docs/current/extensions/axios.md
@@ -404,7 +404,7 @@ export class MainConfiguration {
   async onReady(container: IMidwayContainer) {
   	const httpServiceFactory = await container.getAsync(axios.HttpServiceFactory);
     const customAxios = httpServiceFactory.get('customAxios');
-    customAxios.interceptors.request.use (
+    customAxios.interceptors.request.use(
       config => {
         //...
       },
@@ -421,13 +421,13 @@ export class MainConfiguration {
 `@midayjs/axios` also exported the original instance of `axios`, which could be useful in helper functions.
 
 ```typescript
-import { axios } from '@midwayjs/axios';
+import { Axios } from '@midwayjs/axios';
 import { ReadStream, createWriteStream } from 'fs';
 import { finished } from 'stream/promises';
 
 async function download(url: string, filename: string) {
   const writer = await createWriteStream(filename);
-  const res = axios.get<ReadStream>(url, {
+  const res = Axios.get<ReadStream>(url, {
     responseType: 'stream',
   });
   res.data.pipe(writer);

diff --git a/site/i18n/en/docusaurus-plugin-content-docs/current/extensions/koa.md b/site/i18n/en/docusaurus-plugin-content-docs/current/extensions/koa.md
@@ -17,7 +17,6 @@ The `@midwayjs/koa` package uses `koa @2` and integrates `@koa/router` as the ba
 
 ```bash
 $ npm i @midwayjs/koa@3 --save
-$ npm i @types/koa --save-dev
 ```
 
 Or reinstall the following dependencies in `package.json`.
@@ -28,10 +27,6 @@ Or reinstall the following dependencies in `package.json`.
     "@midwayjs/koa": "^3.0.0",
     // ...
   },
-  "devDependencies": {
-    "@types/koa": "^2.13.4 ",
-    // ...
-  }
 }
 ```
 
@@ -230,11 +225,11 @@ All attributes are described as follows:
 | cert | string \| Buffer \| Array<Buffer\|Object> | Optional, Https cert, server certificate |
 | ca | string \| Buffer \| Array<Buffer\|Object> | Optional, Https ca |
 | http2 | boolean | Optional, supported by http2, default false |
-| proxy | boolean | Optional. Whether to enable the proxy. If true, the host / protocol / ip in the request request is obtained from the X-Forwarded-Host / X-Forwarded-Proto / X-Forwarded-For in the Header field. The default value is false |
+| proxy | boolean | Optional, whether to enable the proxy. If it is true, the IP in the request request will be obtained first from the X-Forwarded-For in the Header field. The default is false. |
 | subdomainOffset | number | optional, the offset of the subdomain name, default 2. |
 | proxyIpHeader | string | optional. obtains the field name of the proxy ip address. the default value is X-Forwarded-For |
 | maxIpsCount | number | optional. the maximum number of ips obtained, which is 0 by default. |
-| serverTimeout | number | Optional, server-side timeout configuration, unit seconds. |
+| serverTimeout | number | Optional, server timeout configuration, the default is 2 * 60 * 1000 (2 minutes), in milliseconds |
 
 
 ### Modify port
@@ -275,6 +270,35 @@ For more information about this feature, see [Global Prefixes](../controller# Gl
 
 
 
+### Reverse proxy configuration
+
+If you use a reverse proxy such as Nginx, please enable the `proxy` configuration.
+
+```typescript
+// src/config/config.default
+export default {
+   // ...
+   koa: {
+     proxy: true,
+   },
+}
+```
+
+The `X-Forwarded-For` Header is used by default. If the proxy configuration is different, please configure a different Header yourself.
+
+```typescript
+// src/config/config.default
+export default {
+   // ...
+   koa: {
+     proxy: true,
+     proxyIpHeader: 'X-Forwarded-Host'
+   },
+}
+```
+
+
+
 ### Https configuration
 
 In most cases, please use external agents as much as possible to complete the implementation of Https, such as Nginx.

diff --git a/site/i18n/en/docusaurus-plugin-content-docs/current/release_schedule.md b/site/i18n/en/docusaurus-plugin-content-docs/current/release_schedule.md
@@ -2,8 +2,9 @@
 
 The following table shows the overall maintenance rhythm and plan of Midway.
 
-| Release | Status | Initial Release | Active LTS Start | Maintenance LTS Start | End-of-life |
-| --- | --- | --- | --- | --- | --- |
-| midway v1(inner v6) | **End-of-Life** | 2018-06-14 | 2018-10 | 2020-04 | 2022-04 |
-| midway v2(inner v7) | **Maintenance LTS** | 2020-10 | 2021-02 | 2021-10 | 2024-04 |
-| midway v3(inner v8) | **Active LTS** | 2022-01 | 2022-06 |  |  |
+| Release              | Status              | Initial Release | Active LTS Start | Maintenance LTS Start | End-of-life |
+| -------------------- | ------------------- | --------------- | ---------------- | --------------------- | ----------- |
+| midway v1（inner v6) | **End-of-Life**     | 2018-06-14      | 2018-10          | 2020-04               | 2022-04     |
+| midway v2（inner v7) | **Maintenance LTS** | 2020-10         | 2021-02          | 2021-10               | 2024-04     |
+| midway v3（inner v8) | **Maintenance LTS** | 2022-01         | 2022-06          | 2023-10               |             |
+| midway v4（inner v9) | **Development**     |                 |                  |                       |             |