From ae5f56f3e9b60eaa3507db44736020f3a13ec6f1 Mon Sep 17 00:00:00 2001 From: Maledong Date: Thu, 14 Feb 2019 16:20:26 +0800 Subject: [PATCH] chore: Add principles for English titles and change all English titles (#3444) Due to there're too many typo errors in the English titles when translating, we have to force some principles and update them all together. --- CONTRIBUTING.md | 16 +++++++++++- CONTRIBUTING.zh-CN.md | 14 +++++++++++ docs/source/en/advanced/cluster-client.md | 12 ++++----- docs/source/en/advanced/loader.md | 28 ++++++++++----------- docs/source/en/advanced/plugin.md | 10 ++++---- docs/source/en/advanced/view-plugin.md | 10 ++++---- docs/source/en/basics/config.md | 10 ++++---- docs/source/en/basics/controller.md | 30 +++++++++++------------ docs/source/en/basics/env.md | 8 +++--- docs/source/en/basics/extend.md | 9 +++---- docs/source/en/basics/middleware.md | 4 +-- docs/source/en/basics/plugin.md | 19 +++++++------- docs/source/en/basics/router.md | 10 ++++---- docs/source/en/basics/schedule.md | 4 +-- docs/source/en/basics/service.md | 2 +- docs/source/en/core/cluster-and-ipc.md | 4 +-- docs/source/en/core/cookie-and-session.md | 6 ++--- docs/source/en/core/deployment.md | 2 +- docs/source/en/core/development.md | 28 ++++++++++----------- docs/source/en/core/error-handling.md | 6 ++--- docs/source/en/core/httpclient.md | 24 +++++++++--------- docs/source/en/core/logger.md | 6 ++--- docs/source/en/core/security.md | 14 +++++------ docs/source/en/core/view.md | 18 ++++++-------- docs/source/en/faq.md | 10 ++++---- docs/source/en/intro/egg-and-koa.md | 8 +++--- docs/source/en/intro/index.md | 5 ++-- docs/source/en/intro/quickstart.md | 14 +++++------ docs/source/en/style-guide.md | 2 +- docs/source/en/tutorials/mysql.md | 8 +++--- docs/source/en/tutorials/passport.md | 2 +- docs/source/en/tutorials/progressive.md | 2 +- docs/source/en/tutorials/restful.md | 18 +++++++------- docs/source/en/tutorials/sequelize.md | 6 ++--- docs/source/en/tutorials/socketio.md | 22 ++++++++--------- docs/source/en/tutorials/typescript.md | 8 +++--- docs/source/zh-cn/core/httpclient.md | 4 +-- docs/source/zh-cn/tutorials/sequelize.md | 2 +- 38 files changed, 215 insertions(+), 190 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4664e5a861..2eb277f94e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,7 +132,20 @@ BREAKING CHANGE: Look at [these files](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit) for more details. -## Release +### Principles of English Translations + +We follow the normal principles of English articles when translating, however, due to there're some special principles of titles, we should follow these rules: + +- For nouns, verbs, pronouns, adjectives and adverbs, capitalize the first character. For prepsitions, articles, conjections, interjections and auxiliary words, the first character should be in lowercase. **the character of the first word and the last word for title should be capitalized, regardless of what it is**. +- For proper nouns such as the direct reference of a variable or the name of a plugin, we must use backtick (underneath the 'Esc') to surround them and keep what they are in origin. +- For prepsitions more than 5 characters, their first characters should be also capitalized, otherwise not. +- For some very important titles or some fixed proper nouns such as methods of Http: POST,GET,PUT,DELETE, every charater can be capitalized (USE WITH CAUTION). +- If the article belongs to the form of O-V (Object-Verb) such as "Config Management", we'd better translate it as "Management Configuration", or "Managing Configuration" in the form of "gerund+noun". +- If your title is taken as a sentence, write in 'Sentence Case' (e.g: In FAQ, each title is actually an English sentence). + +For more info, please refer [English Title Case]. + +## Release Management Egg uses semantic versioning in release process based on [semver]. @@ -185,3 +198,4 @@ All tags mentioned above means the tags of npm in `package.json`. [1.x milestone]: https://github.com/eggjs/egg/milestone/1 [npm]: http://npmjs.com/ [How to deploy an npm package]: https://fengmk2.com/blog/2016/how-i-publish-a-npm-package +[English Title Case]: https://headlinecapitalization.com/ diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md index 43cabc5d79..8aeb956890 100644 --- a/CONTRIBUTING.zh-CN.md +++ b/CONTRIBUTING.zh-CN.md @@ -136,6 +136,19 @@ BREAKING CHANGE: 详情请查看具体[文档](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit)。 +### 英语翻译规范 + +英语正文按照一般英语语法规律书写即可，但标题比较特殊，应该按照以下规范进行书写： + +- 名词、动词、代词、形容词、副词等首字母大写，介词、冠词、连词、感叹词和助词首字母小写，*标题第一个单词、最后一个单词无论词性首字母应该大写*。 +- 专有名词（如直接引用某个变量，或者某个插件名称等），必须使用反单引号（键盘上 Esc 正下方）进行引用，并保持原来大小写。 +- 超过5个字母的介词首字母应该大写，否则一律小写。 +- 如果是重要提示性标题，或者是专有名称标题（例如 Http 请求方法：GET，POST，PUT，DELETE），可以全部字母都用大写（慎重考虑）。 +- 如果标题属于“动宾”性质的短语（如“配置管理”），尽量翻译成“宾+动词名词”的形式（Configuration Management），或者是“动名词+宾语”的形式（Managing Configuration）。 +- 如果标题被当做一个完整的英语句子，请按照英语句子的语法格式大小写（如：常见问题 FAQ 中每一个标题都是一个英语句子）。 + +有关详情，可以参考[英语标题大小写]。 + ## 发布管理 egg 基于 [semver] 语义化版本号进行发布。 @@ -189,3 +202,4 @@ egg 基于 [semver] 语义化版本号进行发布。 [1.x milestone]: https://github.com/eggjs/egg/milestone/1 [npm]: http://npmjs.com/ [我是如何发布一个 npm 包的]: https://fengmk2.com/blog/2016/how-i-publish-a-npm-package +[英语标题大小写]: https://headlinecapitalization.com/ diff --git a/docs/source/en/advanced/cluster-client.md b/docs/source/en/advanced/cluster-client.md index 19f62df341..1985eb502e 100644 --- a/docs/source/en/advanced/cluster-client.md +++ b/docs/source/en/advanced/cluster-client.md @@ -22,7 +22,7 @@ In addition, it's relatively inefficient to transmit data via messenger, since m So is there any better way? The answer is: YES! We provide a new type of model to reduce the complexity of this type of client encapsulation. The new Model bypasses the Master by establishing a direct socket between Agent and Worker. And as an external interface, Agent maintains shared connection among multiple Worker processes. -## core idea +## Core Idea - Inspired by the [Leader/Follower](http://www.cs.wustl.edu/~schmidt/PDF/lf.pdf) model. - The client is divided into two roles: @@ -56,7 +56,7 @@ win / +------------------+ \ lose +--------+ +-------------------+ ``` -## Client interface type abstraction +## Client Interface Type Abstraction We abstract the client interface into the following two broad categories, which is also a specification of the client interface. For clients that are in line with norms, we can automatically wrap it as Leader / Follower mode. @@ -108,12 +108,12 @@ class Client extends Base { } ``` -## exception handling +## Exception Handling - If Leader "dies", a new round of port contention will be triggered. The instance which seizes the port will be elected as the new Leader. - To ensure that the channel between Leader and Follower is healthy, heartbeat mechanism needs to be introduced. If the Follower does not send a heartbeat packet within a fixed time, the Leader will proactively disconnect from the Follower, which will trigger the reinitialization of Follower. -## protocol and time series to invoke +## Protocol and Time Series to Invoke Leader and Follower exchange data via the following protocols: @@ -159,7 +159,7 @@ Leader and Follower exchange data via the following protocols: | | ``` -## specific use +## Specific Usage In the following I will use a simple example to introduce how to make a client support Leader / Follower mode in the framework. @@ -494,7 +494,7 @@ in conclusion: Students who are interested may have look at [enhanced multi-process development model](https://github.com/eggjs/egg/issues/322) discussion process. -## the configuration items related to cluster-client in the framework +## The Configuration Items Related to Cluster-Client in the Framework ```js /** diff --git a/docs/source/en/advanced/loader.md b/docs/source/en/advanced/loader.md index a618c21ba6..21d2c6c977 100644 --- a/docs/source/en/advanced/loader.md +++ b/docs/source/en/advanced/loader.md @@ -89,7 +89,7 @@ From the scene above we can see the relationship of application, plugin and fram +-----------------------------------+--------+ ``` -## loadUnit +## LoadUnit Egg regards application, framework and plugin as loadUnit, because they are similar in code structure, here is the directory structure: @@ -164,7 +164,7 @@ The plugin1 is framework1's dependent plugin, the object key order of plugin1 af See [Loader.getLoadUnits](https://github.com/eggjs/egg-core/blob/65ea778a4f2156a9cebd3951dac12c4f9455e636/lib/loader/egg_loader.js#L233) method for details. -### File order +### File Order The files that will be loaded by default are listed above. Egg will load files by the following order, each file or directory will be loaded according to loadUnit order (application, framework and plugin are different): @@ -250,15 +250,15 @@ If you need to modify the expiring time, please see [this document](https://gith Deprecated methods: -## beforeStart +## `beforeStart` `beforeStart` is called during the loading process, all of its methods are running in parallel. So we usually execute some asynchronized methods (e.g: Check the state of connection, in [`egg-mysql`](https://github.com/eggjs/egg-mysql/blob/master/lib/mysql.js) we use this method to check the connection state with mysql). When all the tasks in `beforeStart` finished, the state will be `ready`. It's NOT recommended to excute a function that consumes too much time there, which will cause the expiration of application's start.plugin developers should use `didLoad` instead, for application developers, `willReady` is the replacer. -## ready +## `ready` All the methods mounted on `ready` will be executed when load ends, and after all the methods in `beforeStart` have finished executing. By the time Http server's listening also starts. This means all the plugins are fully loaded and everything is ready, So we use it to process some tasks after start. For developers now, we use `didReady` instead. -## beforeClose +## `beforeClose` All the methods mounted on `beforeClose` are called in an inverted order after `close` method in app/agent instance is called. E.g: in [`egg`](https://github.com/eggjs/egg/blob/master/lib/egg.js), we close logger, remove listening methods ...,ect.Developers SHOULDN'T use `app.beforeClose` directly now, but in the form of class to implement `beforeClose` instead. @@ -266,7 +266,7 @@ __We don't recommend to use this function in a PROD env, because the process may What's more, we can use [`egg-development`](https://github.com/eggjs/egg-development#loader-trace) to see the loading process. -### Loading File rules +### File-Loading Rules The framework will convert file names when loading files, because there is a difference between the file naming style and the API style. We recommend that files use underscores, while APIs use lower camel case. For examplem `app/service/user_info.js` will be converted to `app.service.userInfo`. @@ -348,7 +348,7 @@ The mention above is just a description of the Loader wording, please see [Frame Loader also supports some low level APIs to simplify code when extending, [here](https://github.com/eggjs/egg-core#eggloader) are all APIs. -### loadFile +### `loadFile` Used to load a file, such as loading `app/xx.js`: @@ -368,7 +368,7 @@ module.exports = app => { If the file exports a function, then the function will be called with `app` as its parameter, otherwise uses this value directly. -### loadToApp +### `loadToApp` Used to load files from a directory into the app, such as `app/controller/home.js` to `app.controller.home`. @@ -387,7 +387,7 @@ The method has three parameters `loadToApp(directory, property, LoaderOptions)`: 2. Property is app's property. 3. [LoaderOptions](#LoaderOptions) are some configurations. -### loadToContext +### `loadToContext` The difference between loadToApp and loadToContext is that loadToContext loads files into ctx instead of app, and it's a lazy loading. It puts files into a temp object when loading, and instantiates objects when calling ctx APIs. @@ -420,7 +420,7 @@ So this class will only be instantiated when first calling, and will be cached a ### LoaderOptions -#### ignore [String] +#### `ignore [String]` `ignore` could ignore some files, supports glob, the default is empty. @@ -431,7 +431,7 @@ app.loader.loadToApp(directory, 'controller', { }); ``` -#### initializer [Function] +#### `initializer [Function]` Processing each file exported values, the default is empty. @@ -452,7 +452,7 @@ app.loader.loadToApp(directory, 'model', { }); ``` -#### caseStyle [String] +#### `caseStyle [String]` File conversion rules, could be `camel`, `upper`, `lower`, the default is `camel`. @@ -470,7 +470,7 @@ app/controller | lower app/middleware | lower app/service | lower -#### override [Boolean] +#### `override [Boolean]` Overriding or throwing exception when encounter existing files, the default is false. @@ -484,7 +484,7 @@ app/controller | true app/middleware | false app/service | false -#### call [Boolean] +#### `call [Boolean]` Calling when export's object is function, and get the return value, the default is true diff --git a/docs/source/en/advanced/plugin.md b/docs/source/en/advanced/plugin.md index aa03f886da..6aec13b64f 100644 --- a/docs/source/en/advanced/plugin.md +++ b/docs/source/en/advanced/plugin.md @@ -129,11 +129,11 @@ The `dependencies` and `optionalDependencies` are learnt from `npm`, most time w Attention: if you are using `optionalDependencies`, framework won't verify the activation of these dependencies, they are only for sorting loading orders. In such situation, the plugin will go through other ways such as `interface detection` to decide processing logic. -## What can plugin do? +## What can Plugin Do? We've discussed what plugin is. Now what can it do? -### Built-in Objects API Extension +### Built-in Objects API Extensions Extend the built-in objects of the framework, just like the application @@ -181,7 +181,7 @@ Extend the built-in objects of the framework, just like the application }; ``` -### Initialization on application starting +### Initialization on Application Starting - If you want to read some local config before startup: @@ -394,7 +394,7 @@ As you can see, all we need to do for this plugin is passing the fields that nee } ``` -##### Dynamically Instantiate +##### Dynamically Instantiating Instead of declaring the configuration in the configuration file in advance, we can dynamically initialize an instance at the runtime of the application. @@ -468,7 +468,7 @@ It's well welcomed to your contributions to the new plugins, but also hope you f } ``` -## Why do not use the npm package name as the plugin name? +## Why Do Not Use the `npm` Package Name as the Plugin Name? Egg defines the plugin name through the `eggPlugin.name`, it is only unique in application or framework, that means **many npm packages might get the same plugin name**, why design in this way? diff --git a/docs/source/en/advanced/view-plugin.md b/docs/source/en/advanced/view-plugin.md index ccd1d0a9ee..157dc6441a 100644 --- a/docs/source/en/advanced/view-plugin.md +++ b/docs/source/en/advanced/view-plugin.md @@ -5,7 +5,7 @@ In most cases, we need to read the data, render the template and then present it This article describes the framework's specification constraints on the View plugin, and we can use this to encapsulate the corresponding template engine plugin. The following takes [egg-view-ejs] as an example. -## Plugin directory structure +## Plugin Directory Structure ```bash egg-view-ejs @@ -21,7 +21,7 @@ egg-view-ejs └── package.json ``` -## Plugin naming convention +## Plugin Naming Convention * Follow the [plugin development specification](./plugin.md) * According to the convention, the names of plugins start with `egg-view-` @@ -46,7 +46,7 @@ module.exports = { }; ``` -## View base class +## View Base Class The next step is to provide a View base class that will be instantiated on each request. @@ -96,7 +96,7 @@ The three parameters of the `renderString` method: * locals: same with `render`. * viewOptions: same with `render`. -## Plugin configuration +## Plugin Configuration According to the naming conventions mentioned above, the configuration name is generally the name of the template engine, such as ejs. @@ -173,7 +173,7 @@ First declare a dependency on [egg-security]: Besides, the framework provides [app.injectCsrf](../core/security.md#appinjectcsrfstr) and [app.injectNonce](../core/security.md#appinjectnonncestr), for more information on [security section](../core/security.md). -### Unit tests +### Unit Tests As a high-quality plugin, perfect unit testing is indispensable, and we also provide lots of auxiliary tools to make it painless for plugin developers to write tests with, see [unit testing](../core/unittest.md) and [plugin](./plugin.md) docs. diff --git a/docs/source/en/basics/config.md b/docs/source/en/basics/config.md index d3e54242cd..48c5234266 100644 --- a/docs/source/en/basics/config.md +++ b/docs/source/en/basics/config.md @@ -10,7 +10,7 @@ Here are some common control tactics: we choose the last strategy, namely **configure with code**, The change of configuration should be also released after reviewing. The application package itself is capable to be deployed in several environments, only need to specify the running environment. -### Multiple environment configuration +### Multiple Environment Configuration This framework supports loading configuration according to the environment and defining configuration files of multiple environments. For more details, please check [env](../basics/env.md). @@ -25,7 +25,7 @@ config The corresponding configuration file will be loaded simultaneously when you set up env and the default configuration with the same name will be overwritten. For example, `prod` environment will load `config.prod.js` and `config.default.js`. As a result, `config.prod.js` will overwrite the configuration with identical name in `config.default.js`. -### How to write configuration +### How to Write Configuration The configuration file returns an object which could overwrite some configurations in the framework. Application can put its own business configuration into it for convenient management. @@ -84,7 +84,7 @@ module.exports = appInfo => { }; ``` -### Sequence of loading configurations +### Sequence of Loading Configurations Applications, plugin components and framework are able to define those configs. Even though the structure of catalog is identical but there is priority (application > framework > plugin). Besides, the running environment has the higher priority. @@ -99,7 +99,7 @@ Here is one sequence of loading configurations under "prod" environment, in whic **Note: there will be plugin loading sequence, but the approximate order is similar. For specific logic, please check the [loader](../advanced/loader.md) .** -### Merging rule +### Rules of Merging Configs are merged using deep copy from [extend2] module, which is forked from [extend] and process array in a different way. @@ -115,7 +115,7 @@ extend(true, a, b); ``` As demonstrated above, the framework will overwrite arrays instead of merging them. -### Configuration result +### Configuration Result The final merged config will be dumped to `run/application_config.json`(for worker process) and `run/agent_config.json`(for agent process) when the framework started, which can help analyzing problems. diff --git a/docs/source/en/basics/controller.md b/docs/source/en/basics/controller.md index dd51c0138e..6987838045 100644 --- a/docs/source/en/basics/controller.md +++ b/docs/source/en/basics/controller.md @@ -200,7 +200,7 @@ The remaining part is the actual content of this response. It can be seen from the above HTTP request examples that there are many places can be used to put user's request data. The framework provides many convenient methods and attributes by binding the Context instance to Controllers to acquire parameters sent by users through HTTP request. -### query +### `query` Usually the Query String, string following `?` in the URL, is used to send parameters by request of GET type. For example, `category=egg&language=node` in `GET /posts?category=egg&language=node` is the parameter that user sends. We can acquire this parsed parameter body through `ctx.query`: @@ -229,7 +229,7 @@ if (key.startsWith('egg')) { Or if someone passes parameters with same keys in Query String on purpose, system error may be thrown. To avoid this, the framework guarantee that the parameter must be a string type whenever it is acquired from `ctx.query`. -#### queries +#### `queries` Sometimes our system is designed to accept same keys sent by users, like `GET /posts?category=egg&id=1&id=2&id=3`. For this situation, the framework provides `ctx.queries` object to parse Query String and put duplicated data into an array: @@ -248,7 +248,7 @@ class PostController extends Controller { All key on the `ctx.queries` will be an array type if it has a value. -### Router params +### Router Params In [Router](./router.md) part, we say Router is allowed to declare parameters which can be acquired by `ctx.params`. @@ -263,7 +263,7 @@ class AppController extends Controller { } ``` -### body +### `body` Although we can pass parameters through URL, but constraints exist: @@ -310,7 +310,7 @@ If user request exceeds the maximum length for parsing that we configured, the f **A common mistake is to confuse `ctx.request.body` and `ctx.body`(which is alias for `ctx.response.body`).** -### Acquire the submitted files +### Acquiring the Submitted Files The `body` in the request can carry parameters as well as files. Generally speaking, our browsers always send files in `multipart/form-data`, and we now have two kinds of ways supporting submitting and acquiring files with the help of the framework's plugin [Multipart](https://github.com/eggjs/egg-multipart). @@ -325,9 +325,9 @@ exports.multipart = { }; ``` -2) Submitting / Acquiring files: +2) Submitting / Acquiring Files: -1. For single file: +1. For Single File: Your HTML static front-end codes should look like this below: ```html @@ -366,7 +366,7 @@ module.exports = class extends Controller { }; ``` -2. For multiple files: +2. For Multiple Files: For multiple files, with the help of `ctx.request.files`, we can loop each of them and do what process we like: @@ -412,7 +412,7 @@ module.exports = class extends Controller { - #### `Stream` Mode If you are very familiar with `Stream` in Nodejs, you can choose this way. In a controller, we can fetch the uploaded files through `ctx.getFileStream()`. -1. For single file： +1. For Single File： ```html
@@ -458,7 +458,7 @@ To acquire the uploaded files easily, there're two conditions at least: - Only ONE file per time. - The field of uploading file MUST be after the other fields in a form, otherwise you cannot get other fields after getting the file stream. -2. For multiple files: +2. For Multiple Files: For multiple files, you should do the following instead of using `ctx.getFileStream()`: @@ -565,7 +565,7 @@ module.exports = { For more tech details about this, please refer [Egg-Multipart](https://github.com/eggjs/egg-multipart). -### header +### `header` Apart from URL and request body, some parameters can be sent by request header. The framework provides some helper attributes and methods to retrieve them. @@ -727,7 +727,7 @@ class PostController extends Controller { The parameter validation is done by [Parameter](https://github.com/node-modules/parameter#rule), and all supported validation rules can be found in its document. -#### Customizing validation rules +#### Customizing Validation Rules In addition to built-in validation types introduced in the previous section, sometimes we hope to customize several validation rules to make the development more convenient and now customized rules can be added through `app.validator.addRule(type, check)`. @@ -798,7 +798,7 @@ class PostController extends Controller { As to which status code should be used for a specific case, please refer to status code meanings on [List of HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) -### Setting Body +### Body Setting Most data is sent to requesters through the body and, just like the body in the request, the body sent by the response demands a set of corresponding Content-Type to inform clients how to parse data. @@ -942,7 +942,7 @@ module.exports = { When the CSRF validation is enabled, the client should bring CSRF token as well when it sends a JSONP request, if the page where the JSONP sender belongs to shares the same domain with our services, CSRF token in Cookie can be read(CSRF can be set manually if it is absent), and is brought together with the request. -##### referrer Validation +##### Validation Reference The CSRF way can be used for JSONP request validation only if the main domains are the same, while providing JSONP services for pages in different domains, we can limit JSONP senders into a controllable rang by configuring the referrer whitelist. @@ -1003,7 +1003,7 @@ exports.jsonp = { **If both CSRF and referrer validation are enabled, the request sender passes any one of them passes the JSONP security validation.** -### Setting Header +### Header Setting We identify whether the request is successful or not by using the status code and set response content in the body. By setting the response header, extended information can be set as well. diff --git a/docs/source/en/basics/env.md b/docs/source/en/basics/env.md index 1287df03d7..9963d71cae 100644 --- a/docs/source/en/basics/env.md +++ b/docs/source/en/basics/env.md @@ -17,15 +17,15 @@ Egg has two ways to configure runtime environment: EGG_SERVER_ENV=prod npm start ``` -## Access to the runtime environment in Application +## Access to the Runtime Environment in Application Egg provides a variable `app.config.env` to represent the current runtime environment of application. -## Configurations of runtime environment +## Configurations of Runtime Environment Different running environment corresponds to different configurations, read [Configuration of Config](./config.md) in detail. -## Difference from NODE_ENV +## Difference from `NODE_ENV` Lots of Node.js applications use `NODE_ENV` to distinguish the runtime environment, but `EGG_SERVER_ENV` distinguishes the environments much more specific. Generally speaking, there are local environment, test environment, production environment during the application development. In addition to the local development environment and the test environment, other environments are collectively referred to as the **Server Environment** and their `NODE_ENV` should be set to `production`. What's more, npm will use this variable and will not install the devDependencies when you deploy applications, so `production` should also be applied. @@ -39,7 +39,7 @@ Default mapping of `EGG_SERVER_ENV` and `NODE_ENV` (will generate `EGG_SERVER_EN For example, `EGG_SERVER_ENV` will be set to prod when `NODE_ENV` is set as `production` and `EGG_SERVER_ENV` is not specified. -## Customize environment +## Environment Customization In normal development process, it's not limit to these environments mentioned above. So you can customize environment for your development process. diff --git a/docs/source/en/basics/extend.md b/docs/source/en/basics/extend.md index 65ff74d734..4a5a285c40 100644 --- a/docs/source/en/basics/extend.md +++ b/docs/source/en/basics/extend.md @@ -28,7 +28,7 @@ The object `app` is just the same aspect as the global application object in Koa }; ``` -### How to extend +### How to Extend Egg will merge the object defined in `app/extend/application.js` with the prototype of Application object in Koa, then generate object `app` which is based on the extended prototype when application is started. @@ -134,7 +134,7 @@ So many properties and methods in `ctx` can also be accessed in `request` object Here are the properties and methods in `ctx` which can also be accessed by Request aliases: [Koa - Request aliases](http://koajs.com/#request-aliases) -### How to extend +### How to Extend Egg will merge the object defined in `app/extend/request.js` and the prototype of `request` object built in egg. And it will generate a `request` object which is based on the extended prototype when deal with request. @@ -163,7 +163,7 @@ So many properties and methods in `ctx` can also be accessed in `response` objec Here are the properties and methods in `ctx` which can also be accessed by Response aliases: [Koa Response aliases](http://koajs.com/#response-aliases) -### How to extend +### How to Extend Egg will merge the object defined in `app/extend/response.js` and the prototype of `response` object build in egg. And it will generate a `response` object which is based on the extended prototype after dealt with request. @@ -201,7 +201,7 @@ ctx.helper.pathFor('home', { by: 'recent', limit: 20 }) // => /?by=recent&limit=20 ``` -### How to extend +### How to Extend Egg will merge the object defined in `app/extend/helper.js` and the prototype of `helper` object build in egg. And it will generate a `helper` object which is based on the extended prototype after dealt with request. @@ -218,7 +218,6 @@ module.exports = { }; ``` - ## Extend according to environment Besides, we can extend the framework in an optional way according to the environment. For example, if you want `mockXX()` only be able to accessed when doing unittest: diff --git a/docs/source/en/basics/middleware.md b/docs/source/en/basics/middleware.md index 3c0033c7cf..abcf0f094b 100644 --- a/docs/source/en/basics/middleware.md +++ b/docs/source/en/basics/middleware.md @@ -5,7 +5,7 @@ In [the previous chapter](../intro/egg-and-koa.md), we say that Egg is based on ## Writing Middleware -### How to write +### How to Write Let's take a look at how to write a middleware from a simple gzip example. @@ -215,7 +215,7 @@ module.exports = { }; ``` -### match and ignore +### `match` and `ignore` match and ignore share the same parameter but do the opposite things. match and ignore cannot be configured in the same time. diff --git a/docs/source/en/basics/plugin.md b/docs/source/en/basics/plugin.md index aa67d6cd82..216b1de042 100644 --- a/docs/source/en/basics/plugin.md +++ b/docs/source/en/basics/plugin.md @@ -13,14 +13,13 @@ Plugin mechanism is a major feature of our framework. Not only can it ensure tha Here are some of the issues we think that can arise when using Koa middleware: -1. Middleware loading is sequential and it is the user's responsibility to setup the execution sequence since middleware mechanism can not manage the actual order. This, in fact, is not very friendly. - When the order is not correct, it can lead to unexpected results. +1. Middleware loading is sequential and it is the user's responsibility to setup the execution sequence since middleware mechanism can not manage the actual order. This, in fact, is not very friendly. When the order is not correct, it can lead to unexpected results. 2. Middleware positioning is geared towards intercepting user requests to add additional logic before or after such as: authentication, security checks, logging and so on. However, in some cases, such functionality can be unrelated to the request, for example, timing tasks, message subscriptions, back-end logic and so on. 3. Some features include very complex initialization logic that needs to be done at application startup. This is obviously not suitable for middleware to achieve. To sum up, we need a more powerful mechanism to manage, orchestrate those relatively independent business logic. -### The relationship between middleware, plugins and application +### The Relationship Between Middleware, Plugins and Application A plugin is actually a "mini-application", almost the same as an app: @@ -36,7 +35,7 @@ Their relationship is: * The plugin itself can contain middleware. * Multiple plugins can be wrapped as an [upper frame] (../ advanced / framework.md). -## Using plugins +## Using Plugins Plugins are usually added via the npm module: @@ -71,7 +70,7 @@ You can directly use the functionality provided by the plugin: app.mysql.query(sql, values); ``` -### Configuring plugins +### Configuring Plugins Each configuration item in `plugin.js` supports: @@ -89,7 +88,7 @@ The application does not need the package or path configuration when using the p exports.onerror = false; ``` -### Environment configuration +### Environment Configuration We also support `plugin.{Env}.js`, which will load plugin configurations based on [Runtime](../basics/env.md). @@ -123,7 +122,7 @@ In this way, `npm i --production` in the production environment does not need to * Use this feature only in the application layer. Do not use it in the framework layer. -### Package name and path +### Package Name and Path * The `package` is introduced in the `npm` style which is the most common way to import * `path` is an absolute path introduced when you want to load the plugin from different location such as when a plugin is still at the development stage or not available on `npm` @@ -138,7 +137,7 @@ exports.mysql = { }; ``` -## Plugin configuration +## Plugin Configuration The plugin will usually contain its own default configuration, you can overwrite this in `config.default.js`: @@ -157,7 +156,7 @@ exports.mysql = { Specific consolidation rules can be found in [Configuration] (. / Config.md). -## Plugin list +## Plugin List * Framework has default built-in plugins for enterprise applications [Common plugins](https://eggjs.org/zh-cn/plugins/):   - [onerror](https://github.com/eggjs/egg-onerror) Uniform Exception Handling @@ -174,6 +173,6 @@ Specific consolidation rules can be found in [Configuration] (. / Config.md).   - [view](https://github.com/eggjs/egg-view) Template Engine * More community plugins can be found on GitHub [egg-plugin](https://github.com/topics/egg-plugin). -## Developing a plugin +## Developing a Plugin See the documentation [plugin development](../advanced/plugin.md). diff --git a/docs/source/en/basics/router.md b/docs/source/en/basics/router.md index 52ebd10e61..0d5cc65d86 100644 --- a/docs/source/en/basics/router.md +++ b/docs/source/en/basics/router.md @@ -32,7 +32,7 @@ class UserController extends Controller { ``` This simplest Router is done by now, when users do the request `GET /user/123`, the info function in `user.js` will be invoked. -## Router config in detail +## Router Config in Detail Below is the complete definition of router, parameters can be determined depending on different scenes. @@ -82,7 +82,7 @@ module.exports = app => { }; ``` -### RESTful style URL definition +### RESTful Style URL Definition We provide `app.resources('routerName', 'pathMatch', 'controller')` to generate [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) structures on a path for convenience if you prefer the RESTful style URL definition. @@ -132,7 +132,7 @@ More practical examples will be shown below to demonstrate how to use the router #### Acquiring Parameters -#### via Query String +#### Via Query String ```js // app/router.js @@ -148,7 +148,7 @@ exports.index = async ctx => { // curl http://127.0.0.1:7001/search?name=egg ``` -#### via Named Parameters +#### Via Named Parameters ```js // app/router.js @@ -164,7 +164,7 @@ exports.info = async ctx => { // curl http://127.0.0.1:7001/user/123/xiaoming ``` -#### acquiring complex parameters +#### Acquiring Complex Parameters Regular expressions, as well, can be used in routing rules to acquire parameters more flexibly: diff --git a/docs/source/en/basics/schedule.md b/docs/source/en/basics/schedule.md index 8218f7484a..447ffd3d17 100644 --- a/docs/source/en/basics/schedule.md +++ b/docs/source/en/basics/schedule.md @@ -67,7 +67,7 @@ This scheduled task will be executed every 1 minute on every worker process, the Schedule tasks can specify `interval` or `cron` two different schedule modes. -#### interval +#### `interval` Configure the scheduled tasks by `schedule.interval`, scheduled tasks will be executed every specified time interval. `interval` can be configured as @@ -83,7 +83,7 @@ module.exports = { }; ``` -#### cron +#### `cron` Configure the scheduled tasks by `schedule.cron`, scheduled tasks will be executed at specified timing according to the cron expressions. cron expressions are parsed by [cron-parser](https://github.com/harrisiirak/cron-parser). diff --git a/docs/source/en/basics/service.md b/docs/source/en/basics/service.md index 404f35941e..2b8a2d5ac6 100644 --- a/docs/source/en/basics/service.md +++ b/docs/source/en/basics/service.md @@ -38,7 +38,7 @@ Framework will initialize a new Service instance for every request accessing the - `this.config`: the application's run-time [config](./config.md). - `this.logger`：logger with `debug`，`info`，`warn`，`error`, use to print different level logs, almost the same as [context logger](../core/logger.md#context-logger), but it will append Service file path for quickly track. -### Service ctx in Detail +### Service `ctx` in Detail To get the path chain of user request, the request context is injected by us during the Service initialization, so you are able to get the related information of context directly by `this.ctx` in methods. For detailed information about context, please refer to [Context](./extend.md#context). With `ctx`, we can get various convenient attributes and methods encapsulated by the framework. For example we can use: diff --git a/docs/source/en/core/cluster-and-ipc.md b/docs/source/en/core/cluster-and-ipc.md index ce9cba7fd5..9cb14b44db 100644 --- a/docs/source/en/core/cluster-and-ipc.md +++ b/docs/source/en/core/cluster-and-ipc.md @@ -183,7 +183,7 @@ module.exports = app => { In this example, codes of `agent.js` are run in Agent process, codes of `app.js` are run in the Worker process, and they do the Inter-Process Communication(IPC) through the `messenger` object encapsulated by framework. Details about the IPC are explained in later sections. -### Master VS Agent VS Worker +### Master vs Agent vs Worker When an application starts up, 3 kinds of processes will be forked. @@ -293,7 +293,7 @@ module.exports = app => { *All methods called on `app.messenger` above can be called on `agent.messenger` too.* -#### egg-ready +#### `egg-ready` We mentioned in the example above that, only after egg-ready event occurs can the message be sent. Only after Master makes sure that all Agent process and Worker processes have been started successfully(and ready), can the `egg-ready` message be sent to all Agent and Worker through messenger, notifying that everything is ready and the IPC channel can be used. diff --git a/docs/source/en/core/cookie-and-session.md b/docs/source/en/core/cookie-and-session.md index b378dbe4bf..b49b8d3f80 100644 --- a/docs/source/en/core/cookie-and-session.md +++ b/docs/source/en/core/cookie-and-session.md @@ -188,7 +188,7 @@ The attributes except of `key` are all standard Cookie attributes. With default config, the session cookie is encrypted, not accessible to JS, which ensures user cannot access or modify it. -### Store session in other storage +### Store Session in Other Storage Session is stored in Cookie by default. If a session is too big, there are some troubles. @@ -242,7 +242,7 @@ Do not put per-user's data cache in Session.** ### Session Practice -#### Set session's expiration time +#### Set Session's Expiration Time Session config has a attribute `maxAge`, which controls global expiration time of all sessions of the application. @@ -266,7 +266,7 @@ class UserController extends Controller { } ``` -#### Extend session's expiration time +#### Extend Session's Expiration Time By default, if user requests don't result in modification of Session, egg.js doesn't extend expiration time of the session. diff --git a/docs/source/en/core/deployment.md b/docs/source/en/core/deployment.md index 8c08c0a704..e8967a1817 100644 --- a/docs/source/en/core/deployment.md +++ b/docs/source/en/core/deployment.md @@ -71,7 +71,7 @@ Options: More about [egg-scripts] and [egg-cluster] documents. -#### Dispatch with arguments +#### Dispatch with Arguments Arguments of dispatch can be configured in `config.{env}.js`. diff --git a/docs/source/en/core/development.md b/docs/source/en/core/development.md index 6f03ceec7e..d52c48b6b5 100644 --- a/docs/source/en/core/development.md +++ b/docs/source/en/core/development.md @@ -3,7 +3,7 @@ title: Local Development We provide convenient ways for development, debugging, and unit tests to improve your development experience. -Here, wo will need to use [egg-bin] module (Only used in local development and unit tests. For production environment, please refer to [Deployment](./deployment.md)). +Here, we need to use [egg-bin] module (Only used in local development and unit tests. For production environment, please refer to [Deployment](./deployment.md)). First of all, we need to include `egg-bin` module in `devDependencies`: @@ -15,7 +15,7 @@ $ npm i egg-bin --save-dev Once we have modified code and saved in local development, the app will restart automatically, and our changes will take place right after that. -### Add Script +### Adding Script Add `npm scripts` into `package.json`： @@ -49,7 +49,7 @@ Starting app in local will listen to port 7001 by default. You may assign other Here we mainly cover the usage of the tools, for more details about unit tests, please refer to [here](./unittest.md). -### Add Script +### Adding Script Add `npm scripts` into `package.json`： @@ -65,7 +65,7 @@ And then we can run unit test by `npm test`. ### Environment Configuration -To run test cases, environment need to be set as `env: unittest`. The configuration comes from the combination of both `config.local.js` and `config.unittest.js`. +To run test cases, environment needs to be set as `env: unittest`. The configuration comes from the combination of both `config.local.js` and `config.unittest.js`. ### Run specific test file @@ -79,7 +79,7 @@ $ TESTS=test/x.test.js npm test [glob] expressions are supported here. -### Reporter setting +### Reporter Setting Mocha supports various reporters. Default reporter is `spec`. @@ -91,7 +91,7 @@ $ TEST_REPORTER=dot npm test ![image](https://cloud.githubusercontent.com/assets/156269/21849809/a6fe6df8-d842-11e6-8507-20da63bc8b62.png) -### Timeout setting +### Timeout Setting The default timeout is 30 seconds. We may set our own timeout (in milliseconds). For example, setting timeout to 5 seconds: @@ -99,7 +99,7 @@ The default timeout is 30 seconds. We may set our own timeout (in milliseconds). $ TEST_TIMEOUT=5000 npm test ``` -### Pass Parameters Via argv +### Pass Parameters via argv Besides environment variables, `egg-bin test` also supports passing parameters directly, and it supports all mocha parameters. You may refer to [mocha usage](https://mochajs.org/#usage). @@ -162,7 +162,7 @@ And we may open HTML file of complete code coverage report via `open coverage/lc Just like test, the environment needs to be set to `env:unittest` to run cov, and the configuration comes from the combination of both `config.local.js` and `config.unittest.js`. -### Ignore specific Files +### Ignore Specific Files To ignore some files in code coverage rate calculation, You may use `COV_EXCLUDES` as the environment variable to ignore some specific files that don't need the test converages: @@ -215,9 +215,9 @@ $ DEBUG=egg* npm run dev Detail logs of unit tests progress are able to be viewed via `DEBUG=* npm test`. -### Debug With egg-bin +### Debug with `egg-bin` -#### Add Script +#### Adding Script Add `npm scripts` into `package.json`： @@ -233,7 +233,7 @@ And then we may set breakpoints for debugging our app via `npm run debug`. `egg-bin` will select debug protocol automatically. [Inspector Protocol] will be selected for version 8.x and later. For earlier ones, [Legacy Protocol] is the choice. -In the meantime, It also supports customized debug parameters. +Meanwhile, It also supports customized debug parameters. ```bash $ egg-bin debug --inpsect=9229 @@ -248,7 +248,7 @@ $ egg-bin debug --inpsect=9229 App starts by `env: local` when executing debug . The configuration comes from the combination of both `config.local.js` and `config.unittest.js`. -#### Debug With [DevTools] +#### Debug with [DevTools] The latest DevTools only supports [Inspector Protocol]. Thus you will need to install Node.js 8.x or higher verions to be able to use it. @@ -279,7 +279,7 @@ And then choose one of the following ways: ![DevTools](https://user-images.githubusercontent.com/227713/30419047-a54ac592-9967-11e7-8a05-5dbb82088487.png) -#### Debug With WebStorm +#### Debug with WebStorm `egg-bin` will read environment variable `$NODE_DEBUG_OPTION` set in WebStorm debug mode. @@ -287,7 +287,7 @@ Start npm debug in WebStorm： ![WebStorm](https://user-images.githubusercontent.com/227713/30423086-5dd32ac6-9974-11e7-840f-904e49a97694.png) -#### Debug With [VSCode] +#### Debug with [VSCode] There are 2 ways: diff --git a/docs/source/en/core/error-handling.md b/docs/source/en/core/error-handling.md index 7004199efd..035dfd996a 100644 --- a/docs/source/en/core/error-handling.md +++ b/docs/source/en/core/error-handling.md @@ -55,7 +55,7 @@ class HomeController extends Controller { For convenience of locating problems, exceptions must be guaranteed to be Error object or object based on Error object, which offers a trace of which functions were called. -## Egg takes charge of exceptions +## Egg Takes Charge of Exceptions [egg-onerror](https://github.com/eggjs/egg-onerror), one of Egg's plugin, handles all exceptions thrown in Middleware, Controller and Service, and returns the error as response based on "Accept" in request header field. @@ -67,7 +67,7 @@ For convenience of locating problems, exceptions must be guaranteed to be Error | JSON & JSONP | local & unittest | - | JSON Object or JSONP response body with details | | JSON & JSONP| others | - | JSON object or JSONP response body without details | -### errorPageUrl +### `errorPageUrl` Redirecting to your customized error page by setting `errorPageUrl` in `onerror` plugin. @@ -81,7 +81,7 @@ module.exports = { }; ``` -## Create your universal exception handler +## Create Your Universal Exception Handler Once the default handler no longer meet your needs, you still can customize your owner error handler by onerror's configurations. diff --git a/docs/source/en/core/httpclient.md b/docs/source/en/core/httpclient.md index 4d72740dbe..1e870089ba 100644 --- a/docs/source/en/core/httpclient.md +++ b/docs/source/en/core/httpclient.md @@ -5,7 +5,7 @@ Countless services rely on the HTTP-based communication nowadays, and it is a ve The framework built in [HttpClient] based on [urllib], you can quickly complete any HTTP request. -## Using HttpClient by app +## Using HttpClient by `app` [HttpClient] will initialize to `app.httpclient` automatically during the application's initialization. Also added an method `app.curl(url, options)`, which is equivalent to the `app.httpclient.request(url, options)`. @@ -25,7 +25,7 @@ module.exports = app => { }; ``` -## Using HttpClient by Context +## Using HttpClient by `ctx` Framework also provides `ctx.curl(url, options)` and `ctx.httpclient` in Context, same as app. So it's very easy to use `ctx.curl()` to complete a HTTP request in the Context (such as in the controller) @@ -160,7 +160,7 @@ class NpmController extends Controller { } ``` -## Advanced HTTP request +## Advanced HTTP Request In some real application scenarios, still have some more complex HTTP requests. @@ -237,7 +237,7 @@ form.file('file1', file1); form.file('file2', file2); ``` -### Uploading files in Stream Mode +### Uploading Files in Stream Mode In fact, Stream is the leading in the world of Node.js. If the server supports streaming, the most friendly way is to send the Stream directly. Actually, Stream will be sent in `Transfer-Encoding: chunked` transmission coding format, which is implemented by [HTTP] module automatically. @@ -268,7 +268,7 @@ class NpmController extends Controller { } ``` -## options Parameters in Detail +## Options Parameters in Detail Due to the complexity of HTTP Request, the options parameters of `httpclient.request(url, options)` quite large. The actual usage of each optional parameter will be shown with descriptions and coding as below. @@ -686,7 +686,7 @@ Then it works correctly, and all requests that go through HttpClient can be view **Note: the pulgin only start in local environments by defalut** -## Known issues +## Known Issues ### Connection Timeout @@ -706,25 +706,25 @@ Then it works correctly, and all requests that go through HttpClient can be view - Scene: usually the server actively disconnects the socket connection, causing the HTTP request link exceptions. - Troubleshooting Suggestion: please check if server has network exception at that time -### Service is unreachable +### Service is Unreachable - Exception: `RequestError, code: ECONNREFUSED, status: -1` - Scene: usually because the requested URL which attached IP or the port cannot connect successfully. - Troubleshooting Suggestion: make sure the IP or port is set correctly -### Domain name is not existing +### Domain Name is Not Existing - Exception: `RequestError, code: ENOTFOUND, status: -1` - Scene: usually the domain name requested by URL cannot be resolved by DNS successfully. - Troubleshooting Suggestion: make sure the domain name exists, and also check to see if the DNS service is properly configured. -### JSON Response data format error +### JSON Response Data Format Error - Exception: `JSONResponseFormatError` - scene: the `dataType=json` is set and this exception is thrown in response data that does not match JSON format. - Troubleshooting Suggestion: make sure that the server no matter what situations are returns the data in JSON format correctly. -## Global `request` and `response` events +## Global `request` and `response` Events In enterprise application scenarios, generally a unified tracer log is needed. To facilitate monitoring HttpClient requests and responses on the app level, we agreed on global `request` and `response` to expose these two events. @@ -745,7 +745,7 @@ To facilitate monitoring HttpClient requests and responses on the app level, we end ``` -### `request` event occurs before the network operation +### `request` Event Occurs before the Network Operation A `request` event is triggered before the request is sent, allowing blocking of the request. @@ -758,7 +758,7 @@ app.httpclient.on('request', req => { }); ``` -### `response` event occurs after the end of network operation +### `response` Event Occurs after the End of Network Operation After the end of request, a `response` event is triggered, so that the external event can be subscribed to the log printing. diff --git a/docs/source/en/core/logger.md b/docs/source/en/core/logger.md index be45b041f9..37dabd4f80 100644 --- a/docs/source/en/core/logger.md +++ b/docs/source/en/core/logger.md @@ -163,7 +163,7 @@ exports.logger = { }; ``` -#### DEBUG Log in Prodction Environment +#### Debug Log in Production Environment To avoid some plugin's DEBUG logs printing in the production environment causing performance problems, the production environment prohibits printing DEBUG-level logs by default. If there is a need to print DEBUG logs for debugging in the production environment, you need to set `allowDebugAtProd` configuration to `ture`. @@ -175,7 +175,7 @@ exports.logger = { }; ``` -### In terminal +### In Terminal By default, Egg will only print out `INFO`, `WARN` and `ERROR` in terminal. (Notice: It only works on `local` and `unittest` env) @@ -208,7 +208,7 @@ exports.logger = { }; ``` -## Create your logger +## Create Your Logger ### Customized diff --git a/docs/source/en/core/security.md b/docs/source/en/core/security.md index b5d678707a..b3ad138bd5 100644 --- a/docs/source/en/core/security.md +++ b/docs/source/en/core/security.md @@ -22,7 +22,7 @@ The framework itself has a rich solution for common security risks on the Web si Security plugins [egg-security](https://github.com/eggjs/egg-security) are built into the framework, provides default security practices. -### Open or close the configuration +### Open or Close the Configuration Note: it is not recommended to turn off the functions provided by the security plugins unless the consequences are clearly confirmed. @@ -37,7 +37,7 @@ exports.security = { }; ``` -### match and ignore +### `match` and `ignore` Match and ignore methods and formats are the same with[middleware general configuration](../basics/middleware.md#match%20and%20ignore). @@ -84,7 +84,7 @@ exports.security = { We'll look at specific scenarios to illustrate how to use the security scenarios provided by the framework for Web security precautions. -## Prevention of security threat `XSS` +## Prevention of Security Threat `XSS` [XSS](https://www.owasp.org/index.php/Cross-site_Scripting_(XSS))（cross-site scripting）is the most common Web attack, which focus on "cross-domain" and "client-side execution." @@ -224,7 +224,7 @@ Configration: * callback - default is `_callback`, you can rename * limit - callback function name length limit, default is 50. -### Other XSS precautions +### Other XSS Precautions Browser itself has some protection against all kinds of attacks, they generally take effect by opening the Web security headers. The framework has built-in support for some common Web security headers. @@ -350,7 +350,7 @@ module.exports = { }; ``` -#### Ignore JSON request(deprecated) +#### Ignore JSON Request(deprecated) **Notice: this configure is deprecated, the attacker can bypass it through [flash and 307](https://www.geekboy.ninja/blog/exploiting-json-cross-site-request-forgery-csrf-using-flash/), please don't enable it in production environment!** @@ -560,7 +560,7 @@ Framework provides `X-Frame-Options` this security header to prevent iframe Phis This configuration can be turned off when you need to embed some trusted third-party web pages. -## Prevention of Security threats `HPP` +## Prevention of Security Threats `HPP` HTTP protocol allows the parameters of the same name appears many times, due to the implementation of the application is not standard, the attacker from the distribution of parameters of transmission key and the value of different parameters, will cause to bypass the consequences of some protection. @@ -642,7 +642,7 @@ exports.security = { }; ``` -## Other build-in security tools +## Other Build-in Security Tools ### ctx.isSafeDomain(domain) diff --git a/docs/source/en/core/view.md b/docs/source/en/core/view.md index 07bd320b18..3fef3ea015 100644 --- a/docs/source/en/core/view.md +++ b/docs/source/en/core/view.md @@ -11,13 +11,13 @@ See [View Plugin](../advanced/view-plugin.md) for more details. Take the officially supported View plugin [egg-view-nunjucks] as an example: -### Install view engine plugin +### Installing View Engine Plugin ```bash $ npm i egg-view-nunjucks --save ``` -### Enable view engine plugin +### Enabling View Engine Plugin ```js // config/plugin.js @@ -27,7 +27,7 @@ exports.nunjucks = { }; ``` -## Configure view plugins +## Configuring View Plugins [egg-view] defines the default configuration of `config.view` @@ -63,7 +63,7 @@ When a file matching given template path is found, the file's full path will be and reused afterward. [egg-view] won't search all directories again for the same template path. -### mapping and defaultViewEngine +### `mapping` and `defaultViewEngine` Every view engine has a view engine name defined when the plugin is enabled. In view configuration, `mapping` defines the mapping @@ -104,7 +104,7 @@ the default view engine will be used. For the applications that use only one view engine, it's recommended to set this option. -### defaultExtension +### `defaultExtension` When calling `render()`, the first argument should contain file extension name, unless `defaultExtension` has been configured. @@ -121,7 +121,7 @@ module.exports = { await ctx.render('home'); ``` -## Render Page +## Rendering Page [egg-view] provides three interfaces in Context. All three returns a Promise: @@ -152,11 +152,9 @@ class HomeController extends Controller { When calling `renderString`, view engine should be specified unless `defaultViewEngine` has been defined. -## Locals +## `locals` -In the process of rendering pages, -we usually need a variable to contain all information that is used in view template. -[egg-view] provides `app.locals` and `ctx.locals`. +In the process of rendering pages, we usually need a variable to contain all information that is used in view template. [egg-view] provides `app.locals` and `ctx.locals`. - `app.locals` is global, usually configured in `app.js`. - `ctx.locals` is per-request, and it merges `app.locals`. diff --git a/docs/source/en/faq.md b/docs/source/en/faq.md index bdb268876a..a68a575c80 100644 --- a/docs/source/en/faq.md +++ b/docs/source/en/faq.md @@ -15,7 +15,7 @@ Thank you for reporting an issue. Most importantly, please understand one thing: the relationship between the `user` and `the maintainer of open source project` is not `Buyer` and `Seller`, the issue is not a customer order either. When you're opening an issue, please hold a mentality of "working together to solve this problem." Do not expect us to serve you unilaterally. -## Why my config don't work? +## Why does my config not work? Framework [Config](./basics/config.md) settings is powerfull, support different environments and different places(framework, plugins, app). @@ -37,9 +37,9 @@ module.exports = appInfo => { By default, logs will print at `${baseDir}/logs`(baseDir is project's base directory) in local environment.But in non-development environments(neither local nor unittest), the logs will print at `$HOME/logs`(such as `/home/admin/logs`). So the logs won't mix in during development and locate in the same place when run in production environment. -## Why not choose PM2 as process management tool? +## Why not choose `PM2` as the process management tool? -1. PM2 itself is too complex to issue problems if any. +1. `PM2` itself is too complex to issue problems if any. 2. Deep optimization could be difficlut to achieve if choosing PM2. 3. Pattern like one leader process communicating with remote services, along with serveral follower processes delegating request to it ([Cluster](./core/cluster-and-ipc.md)), is a rigid demand for reducing connections and data exchange load, espeically when facing applications in very large scale. egg originates from Ant Financial Group and Alibaba Group, we start with applications in that scale at first, so we take these goals into consideration. All of these goals above could be hard to achieve with PM2. @@ -68,7 +68,7 @@ We can start application with PM2 like this: pm2 start server.js ``` -## How to resolve csrf error? +## How to resolve `csrf` error? There are two kinds of common csrf errors: @@ -79,7 +79,7 @@ By default [egg-security](https://github.com/eggjs/egg-security/) plugin built i The error will disappear in the presence of correct csrf token in request. For more implentation details, see [./core/security.md#csrf]. -## In local development environment, why is worker process not restarted automatically when files are modified? +## In local development Environment, why is worker process not restarted automatically when files are modified? Usually this happens when you are using Jetbrains softwares(IntelliJ IDEA, WebStorm, etc.) with `Safe Write` turned on. diff --git a/docs/source/en/intro/egg-and-koa.md b/docs/source/en/intro/egg-and-koa.md index 11d3d60135..fa2551b55f 100644 --- a/docs/source/en/intro/egg-and-koa.md +++ b/docs/source/en/intro/egg-and-koa.md @@ -1,7 +1,7 @@ title: Egg and Koa --- -## Asynchronous programming model +## Asynchronous Programming Model Node.js is an asynchronous world, asynchronous programming models in official API support are all in callback form ，it brings many problems. For example: @@ -10,7 +10,7 @@ Node.js is an asynchronous world, asynchronous programming models in official AP The community has provided many solutions for the problems, the winner is Promise, it is built into ECMAScript 2015. On the basis of Promise, and with the ability of Generator to switch context, we can write asynchronous code in synchronous way with [co] and other third party libraries. Meanwhile [async function], the official solution has been published in ECMAScript 2017 and landed in Node.js 8. -### Async function +### Async Function [Async function] is a syntactic sugar at the language level. In async function, we can use `await` to wait for a promise to be resolved(or rejected, which will throw an exception), and Node.js LTS (8.x) has supported this feature. @@ -57,7 +57,7 @@ At the same time Request and Response are mounted to Context object. Just like E - `set response.body` - `set response.status` -### Exception handling +### Exception Handling Another enormous advantage for writing asynchronous code in synchronous way is that it is quite at ease to handle exception. You can catch all the exceptions thrown in the codes followed the convention with `try catch`. We can easily write a customized exception handling middleware. @@ -75,7 +75,7 @@ async function onerror(ctx, next) { Putting this middleware before others, you can catch all the exceptions thrown by the synchronous or asynchronous code. -## Egg inherits from Koa +## Egg Inherits from Koa As described above, Koa is an excellent framework. However, it is not enough to build an enterprise-class application. diff --git a/docs/source/en/intro/index.md b/docs/source/en/intro/index.md index 13fde0c846..a5ea904e7f 100644 --- a/docs/source/en/intro/index.md +++ b/docs/source/en/intro/index.md @@ -2,6 +2,7 @@ title: What is Egg? --- **Egg is born for building enterprise application and framework**，we hope Egg will give birth to more application framework to help developers and developing team reduce development and maintenance costs. + ## Design principles Since we know well that enterprise applications need to consider how to balance the differences between different teams, seeking common ground while reserving differences in the pursuit of clarifying specification and cooperation, we focus on providing core features for Web development and a flexible and extensible plugin mechanism instead of giant bazaar mode which is popular in common Web frameworks (with integrated such as database, template engine, front-end framework and other functions). We will not make technical selection because default technical selection makes the scalability of the framework too poor to meet a variety of custom requirements. With the help of Egg, it is very easy for architects and technical leaders to build their own framework which is suitable for their business scenarios based on existing technology stack . @@ -10,13 +11,13 @@ The plugin mechanism of Egg is very extensible, **one purpose for one plugin**(E Egg is a convention-over-configuration framework, follows the [Loader](../advanced/loader.md) to do the development, it helps to reduce the cost of learning. Developers no longer work as 'nails'. The cost of communication is very high for a team without convention. it is easy to get fault without convention. However convention is not equal to diffcult extension, instead, Egg does well in extension part, you can build your own framework according to team convention. [Loader](../advanced/loader.md) can help load different default configuration in different environment, Egg default convention can also be covered by your own. -## Differences between community framework +## Differences Between Community Framework [Express] is well used in Node.js community, it is easy and extensible, fit personal project a lot. However, without default convention, standard mvc model has lots of strange impl which would lead to misunderstandings. Egg's teamwork cost is really low by following convention convention-over-configuration. [Sails] is a framework that also follows convention-over-configuration,it does well in extensible work. Compared with Egg, [Sails] supports blueprint REST API, [WaterLine] , Frontend integration, WebSocket and so on, all of these are provided by [Sails]. Egg does not provide these functions, it only has integration of different functional extensions, such as egg-blueprint, egg-waterline, if you use sails-egg to integrate these extensions, [Sails] can be replaced. -## features +## Features - Provide capability to [customizd framework](../advanced/framework.md) base on Egg - Highly extensible [plugin mechanism](../basics/plugin.md) diff --git a/docs/source/en/intro/quickstart.md b/docs/source/en/intro/quickstart.md index d258c48291..59878f936d 100644 --- a/docs/source/en/intro/quickstart.md +++ b/docs/source/en/intro/quickstart.md @@ -9,7 +9,7 @@ By following along with this guide step by step, you can quickly get started wit - Operating System: Linux, OS X or Windows. - Node.js Runtime: 8.x or newer; it is recommended that you use [LTS Releases][Node.js]. -## the Quick Way +## The Quick Way To begin with, let's quickly initialize the project by using a scaffold, which will quickly generate some of the major pieces of the application. @@ -124,7 +124,7 @@ $ open localhost:7001 > - You could write `Controller` with `class` or `exports` style, see more detail at [Controller](../basics/controller.md). > - And `Config` could write with `module.exports` or `exports` style, see more detail at [Node.js modules docs](https://nodejs.org/api/modules.html#modules_exports_shortcut). -### Add Static Assets +### Adding Static Assets Egg has a built-in plugin called [static][egg-static]. In production, it is recommended that you deploy static assets to CDN instead of using this plugin. @@ -142,7 +142,7 @@ app/public └── news.js ``` -### Add Templates for Rendering +### Adding Templates for Rendering In most cases, data are usually read, processed and rendered by the templates before being presented to the user. Thus we need to introduce corresponding template engines to handle it. @@ -315,7 +315,7 @@ exports.news = { }; ``` -### Add Extensions +### Adding Extensions We might encounter a small problem here. The time that we fetched are Unix Time format, @@ -344,7 +344,7 @@ Then use it in the templates. {{ helper.relativeTime(item.time) }} ``` -### Add Middlewares +### Adding Middlewares Suppose that we wanted to prohibit accesses from Baidu crawlers. @@ -385,7 +385,7 @@ Now try it using `curl localhost:7001/news -A "Baiduspider"`. See [Middleware](../basics/middleware.md) for more details. -### Add Configurations +### Adding Configurations When writing business logic, it is inevitable that we need to manage configurations. @@ -424,7 +424,7 @@ class SomeService extends Service { module.exports = SomeService; ``` -### Add Unit Testing +### Adding Unit Testing Unit Testing is very important, and Egg also provides [egg-bin] to help you write tests painless. diff --git a/docs/source/en/style-guide.md b/docs/source/en/style-guide.md index d3da6dbc7e..2889db42d9 100644 --- a/docs/source/en/style-guide.md +++ b/docs/source/en/style-guide.md @@ -42,7 +42,7 @@ module.exports = Object.assign(egg, { }); ``` -## Private properties & Lazy Initialization +## Private Properties & Lazy Initialization * Private properties are mounted with `Symbol`. * The description of Symbol follows the rules of jsdoc, describing the mapped class name + attribute name. diff --git a/docs/source/en/tutorials/mysql.md b/docs/source/en/tutorials/mysql.md index b9048659bc..9f148687c8 100644 --- a/docs/source/en/tutorials/mysql.md +++ b/docs/source/en/tutorials/mysql.md @@ -3,9 +3,9 @@ title: MySQL MySQL is one of the most common and best RDBMS in terms of web applications. It is used in many large-scale websites such as Google and Facebook. -## egg-mysql +## `egg-mysql` -egg-mysql is provided to access both the MySQL databases and MySQL-based online database service. +`egg-mysql` is provided to access both the MySQL databases and MySQL-based online database service. ### Installation and Configuration @@ -116,7 +116,7 @@ module.exports = app => { }; ``` -## Service layer +## Service Layer Connecting to MySQL is a data processing layer in the Web layer. So it is strongly recommended that keeping the code in the Service layer. @@ -318,7 +318,7 @@ try { } ``` -### Automatic control: Transaction with scope +### Automatic Control: Transaction with Scope - API：`beginTransactionScope(scope, ctx)` - `scope`: A generatorFunction which will execute all sqls of this transaction. diff --git a/docs/source/en/tutorials/passport.md b/docs/source/en/tutorials/passport.md index 8c4d925107..1c4d8429c9 100644 --- a/docs/source/en/tutorials/passport.md +++ b/docs/source/en/tutorials/passport.md @@ -19,7 +19,7 @@ The execution sequence of [Passport](http://www.passportjs.org/) is as follows: * Serialize user information to Session * Jump to the specified page -## Using egg-passport +## Using `egg-passport` Below, we will use GitHub login as an example to demonstrate how to use it. diff --git a/docs/source/en/tutorials/progressive.md b/docs/source/en/tutorials/progressive.md index 6f5ffc2615..80346f5dcc 100644 --- a/docs/source/en/tutorials/progressive.md +++ b/docs/source/en/tutorials/progressive.md @@ -205,7 +205,7 @@ $ npm i $ npm test ``` -## Write in the end +## In the End In conclusion, we can see how to make the framework evolution step by step which benefits from Egg's powerful plugin mechanism, code co-build, reusability and modularity. diff --git a/docs/source/en/tutorials/restful.md b/docs/source/en/tutorials/restful.md index 6a3cd19f22..21978874e6 100644 --- a/docs/source/en/tutorials/restful.md +++ b/docs/source/en/tutorials/restful.md @@ -44,7 +44,7 @@ A example of `topics` is shown below: ] ``` -### Retrieve one topic +### Retrieve One Topic - `GET /api/v2/topics/57ea257b3670ca3f44c5beb6` - status code: 200 @@ -65,7 +65,7 @@ A example of `topics` is shown below: } ``` -### Create topics +### Create Topics - `POST /api/v2/topics` - status code: 201 @@ -77,13 +77,13 @@ A example of `topics` is shown below: } ``` -### Update topics +### Update Topics - `PUT /api/v2/topics/57ea257b3670ca3f44c5beb6` - status code: 204 - response body: null -### Error handling +### Error Handling When an error is occurring, 4xx status code is returned if occurred by client-side request parameters and 5xx status code is returned if occurred by server-side logic processing. All error objects are used as the description for status exceptions. @@ -99,7 +99,7 @@ For example, passing invalided parameters from the client may return a response After interface convention, we begin to create a RESTful API. -### Application initialization +### Application Initialization Initializes the application using [egg-init](https://github.com/eggjs/egg-init) in the [quickstart](../intro/quickstart.md) @@ -121,7 +121,7 @@ exports.validate = { }; ``` -### Router registry +### Router Registry First of all, we follower previous design to register [router](../basics/router.md). The framework provides a simply way to create a RESTful-style router and mapping the resources to the corresponding controllers. @@ -134,7 +134,7 @@ module.exports = app => { Mapping the 'topics' resource's CRUD interfaces to the `app/controller/topics.js` using `app.resources` -### Developing controller +### Developing Controller In [controller](../basics/controller.md), we only need to implement the interface convention of `app.resources` [RESTful style URL definition](../basics/router.md#RESTful-style-URL-definition). For example, creating a 'topics' interface: @@ -174,7 +174,7 @@ As shown above, a Controller mainly implements the following logic: 2. create a topic by calling service encapsulates business logic using the validated parameters 3. configure the status code and context according to the interface convention -### Developing service +### Developing Service We will more focus on writing effective business logic in [service](../basics/service.md). @@ -220,7 +220,7 @@ module.exports = TopicService; After developing the Service of topic creation, an interface have been completed from top to bottom. -### Unified error handling +### Unified Error Handling Normal business logic has been completed, but exceptions have not yet been processed. Controller and Service may throw an exception as the previous coding, so it is recommended that throwing an exception to interrupt if passing invalided parameters from the client or calling the back-end service with exception. diff --git a/docs/source/en/tutorials/sequelize.md b/docs/source/en/tutorials/sequelize.md index a3d07b0643..5af1959a57 100644 --- a/docs/source/en/tutorials/sequelize.md +++ b/docs/source/en/tutorials/sequelize.md @@ -14,7 +14,7 @@ brew install mysql brew service start mysql ``` -## Init +## Initialization Init project by `egg-init`: @@ -65,7 +65,7 @@ exports.sequelize = { After completing the above configuration, a project using sequelize is initialized. [egg-sequelize] and [sequelize] also support more configuration items, which can be found in their documentation. -## Init Database and Migrations +## Database and Migrations Initialization Next, let's temporarily leave the code of the egg project, design and initialize our database. First, we quickly create two databases for development and testing locally using the mysql command: @@ -317,7 +317,7 @@ module.exports = app => { }; ``` -- Initialize the file `test/.setup.js`, introduce the factory, and ensure that the data is cleaned after the test is executed to avoid being affected. +- Initialize the file `test/.setup.js`, introduce the factory, and ensure that the data is cleaned after the test is executed to avoid being affected. ```js const { app } = require('egg-mock/bootstrap'); diff --git a/docs/source/en/tutorials/socketio.md b/docs/source/en/tutorials/socketio.md index f6b287c194..692765e8ea 100644 --- a/docs/source/en/tutorials/socketio.md +++ b/docs/source/en/tutorials/socketio.md @@ -51,7 +51,7 @@ exports.io = { > Namespaces are `/` and `/ example`, not`example` -#### uws +#### `uws` **Egg's socket is using `ws`, [uws](https://www.npmjs.com/package/uws) is deprecated due to [some reasons](https://github.com/socketio/socket.io/issues/3319).** @@ -64,7 +64,7 @@ exports.io = { }; ``` -#### redis +#### `redis` [egg-socket.io] has built-in redis support via `socket.io-redis`. In cluster mode, the use of redis can make it relatively simple to achieve information sharing of clients/rooms and so on @@ -115,7 +115,7 @@ location / { } ``` -## Using egg-socket.io +## Using `egg-socket.io` The directory structure of project which has enabled the [egg-socket.io] is as follows: @@ -326,7 +326,7 @@ Module.exports = app => { Here we use [egg-socket.io] to do a small example which supports p2p chat -### client +### Client The UI-related content is not rewritten. It can be called via window.socket @@ -397,11 +397,11 @@ socket.on('res', msg => { }); ``` -### server +### Server -The following is part of the demo code and explains the role of each method +The following is part of the demo code and explains the role of each method: -#### config +#### Config ```js // {app_root}/config/config.${env}.js @@ -420,7 +420,7 @@ exports.io = { }; ``` -#### helper +#### Helper Framework extensions for encapsulating data formats @@ -464,7 +464,7 @@ Format： } ``` -#### middleware +#### Middleware [egg-socket.io] middleware handles socket connection handling @@ -549,7 +549,7 @@ module.exports = () => { }; ``` -#### controller +#### Controller Data exchange of P2P communication is through exchange @@ -579,7 +579,7 @@ class NspController extends controller { module.exports = NspController; ``` -#### router +#### Router ```js // {app_root}/app/router.js diff --git a/docs/source/en/tutorials/typescript.md b/docs/source/en/tutorials/typescript.md index 79f3977c85..663dfaad87 100644 --- a/docs/source/en/tutorials/typescript.md +++ b/docs/source/en/tutorials/typescript.md @@ -37,7 +37,7 @@ The boilerplate above will create a very simple example, for a detailed one plea --- -## Principles of catalogs +## Principles of Catalogs **Some constraints:** @@ -568,7 +568,7 @@ For more detailed info: --- -## Guides to the developments of Plugin/Framework +## Guides to the Developments of Plugin/Framework **Principles:** @@ -614,7 +614,7 @@ declare module 'egg' { } ``` -### The outer framework +### The Outer Framework Definitions: @@ -653,7 +653,7 @@ export default class NewsService extends Service { Here're some questions asked by many people with answers one by one: -### ts won't be loaded when running `npm start` +### `ts` won't be loaded when running `npm start` `npm start` actually runs `egg-scripts start`, however we ONLY integrate `ts-node` in our `egg-bin`, it means ts won'be loaded until we use `egg-bin`. diff --git a/docs/source/zh-cn/core/httpclient.md b/docs/source/zh-cn/core/httpclient.md index 046e64c2bb..3a4b9fe67d 100644 --- a/docs/source/zh-cn/core/httpclient.md +++ b/docs/source/zh-cn/core/httpclient.md @@ -5,7 +5,7 @@ title: HttpClient 为此框架基于 [urllib] 内置实现了一个 [HttpClient]，应用可以非常便捷地完成任何 HTTP 请求。 -## 通过 app 使用 HttpClient +## 通过 `app` 使用 HttpClient 框架在应用初始化的时候，会自动将 [HttpClient] 初始化到 `app.httpclient`。 同时增加了一个 `app.curl(url, options)` 方法，它等价于 `app.httpclient.request(url, options)`。 @@ -25,7 +25,7 @@ module.exports = app => { }; ``` -## 通过 Context 使用 HttpClient +## 通过 `ctx` 使用 HttpClient 框架在 Context 中同样提供了 `ctx.curl(url, options)` 和 `ctx.httpclient`，保持跟 app 下的使用体验一致。 这样就可以在有 Context 的地方（如在 controller 中）非常方便地使用 `ctx.curl()` 方法完成一次 HTTP 请求。 diff --git a/docs/source/zh-cn/tutorials/sequelize.md b/docs/source/zh-cn/tutorials/sequelize.md index 2dd8a8035f..e57c055b34 100644 --- a/docs/source/zh-cn/tutorials/sequelize.md +++ b/docs/source/zh-cn/tutorials/sequelize.md @@ -316,7 +316,7 @@ module.exports = app => { }; ``` -- 初始化文件 `test/.setup.js`，引入 factory，并确保测试执行完后清理数据，避免被影响 +- 初始化文件 `test/.setup.js`，引入 factory，并确保测试执行完后清理数据，避免被影响。 ```js const { app } = require('egg-mock/bootstrap');