docs: add document for built-in objects #914

dead-horse · 2017-05-16T04:30:39Z

Checklist

npm test passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

Description of change

mention-bot · 2017-05-16T04:30:39Z

@dead-horse, thanks for your PR! By analyzing the history of the files in this pull request, we identified @popomore, @atian25 and @huacnlee to be potential reviewers.

codecov · 2017-05-16T04:59:36Z

Codecov Report

Merging #914 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #914   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          28     28           
  Lines         669    669           
=====================================
  Hits          669    669

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 02b02e0...7ad50ad. Read the comment docs.

atian25 · 2017-05-16T05:53:19Z

docs/source/zh-cn/basics/objects.md

@@ -0,0 +1,227 @@
+title: egg 内置基础对象


我把 egg 改成框架吧

atian25 · 2017-05-16T05:53:34Z

docs/source/zh-cn/basics/objects.md

+title: egg 内置基础对象
+---
+
+在往下阅读之前，我们先初步介绍一下框架中内置的一些基础对象，包括从 [koa] 继承而来的 4 个对象（Application, Context, Request, Response) 以及框架扩展的一些对象（Helper, Controller, Service），在后续的文档阅读中我们会经常遇到它们。


atian25 · 2017-05-16T05:55:27Z

docs/source/zh-cn/basics/objects.md

+
+## Context
+
+Context 是一个**请求级别的对象**，继承自 [koa.Context]。在每一次收到用户请求时，框架会实例化一个 Context 对象，这个对象封装了这次用户请求的信息，并提供了许多便捷的方法来获取请求参数或者设置响应信息。框架会将所有的 [service](./service.md) 挂载到 Context 实例上，一些插件也会将一些其他的方法和对象挂载到它上面（[egg-sequelize] 会将所有的 model 挂载在 Context 上。


[Service]

atian25 · 2017-05-16T05:57:33Z

docs/source/zh-cn/basics/objects.md

+  return class UserController extends app.Controller {
+    fetch* () {
+      const id = this.request.query.id;
+      this.ctx.response.body = this.app.cache.get(id);


这里感觉可以稍微提下 this.ctx.body 和 this.ctx.response.body 等价，然后顺手提下 this.request.body 的区别。

req 和 res 要提下么?

req 和 res 先不提了

atian25 · 2017-05-16T05:58:33Z

docs/source/zh-cn/basics/objects.md

+// app/controller/user.js
+
+// 从 egg 上获取
+module.exports = UserController extends require('egg').Controller {


require 另起一行吧。

注明下推荐哪种？

atian25 · 2017-05-16T05:59:38Z

docs/source/zh-cn/basics/objects.md

+
+Helper 自身是一个类，有和 [Controller](#controller) 基类一样的属性，它也会在每次请求时进行实例化，因此 Helper 上的所有函数也能获取到当前请求相关的上下文信息。
+
+### 获取方式


增加在模板里面使用 Helper 的说明?

atian25 · 2017-05-16T06:01:02Z

docs/source/zh-cn/basics/objects.md

+title: egg 内置基础对象
+---
+
+在往下阅读之前，我们先初步介绍一下框架中内置的一些基础对象，包括从 [koa] 继承而来的 4 个对象（Application, Context, Request, Response) 以及框架扩展的一些对象（Helper, Controller, Service），在后续的文档阅读中我们会经常遇到它们。


Config 对象要提到么?

感觉 config 没有什么特殊的，在配置那一章节中已经描述好了

但它也算是 egg 的内置基础对象吧，是不是可以稍微提下，给个链接过去。

本来还准备加上 config 和 logger 的

我等下都加上吧

dead-horse · 2017-05-16T16:39:53Z

@atian25 再看看吧

atian25

其他 +1，写的很赞

atian25 · 2017-05-16T22:21:37Z

docs/source/languages/zh-cn.yml

@@ -26,6 +26,7 @@ guide_toc:
  Get Start: 快速入门
  Basics: 基础功能
  Structure: 目录结构
+  Objects: 内置对象


这篇有点 Concept 的感觉 😍

atian25 · 2017-05-16T22:24:37Z

docs/source/zh-cn/basics/objects.md

+
+### 获取方式
+
+最常见的 context 实例获取方式是在 [Middleware], [Controller] 以及 [Service] 中。[Controller] 中的获取方式在上面的例子中已经展示过了，在 [Service] 中获取和 [Controller] 中获取的方式一样，在 [Middleware] 中获取 Contenxt 实例则和 [koa] 框架在中间件中获取 Context 对象的方式一致。


第一个 context 没大写，第二个拼写错误

atian25 · 2017-05-16T22:31:38Z

docs/source/zh-cn/basics/objects.md

+    fetch* () {
+      const id = this.request.query.id;
+      const user = this.app.cache.get(id);
+      this.body = this.helper.formatUser(user);


this -> ctx

atian25 · 2017-05-16T22:32:47Z

docs/source/zh-cn/basics/objects.md

+
+## Config
+
+我们推荐应用开发遵循配置和代码分离的原则，将一些需要硬编码的业务配置都放到配置文件中，同时配置文件支持各个不同的运行环境使用不同的配置，使用起来也非常方便，所有框架、插件和应用级别的配置都可以通过 Config 对象获取到，关于框架的配置，可以详细阅读[Config 配置](./config.md)章节。


[Config 配置] 前面少个空格

atian25 · 2017-05-16T22:34:44Z

docs/source/zh-cn/basics/objects.md

+// app/controller/user.js
+module.exports = app => {
+  return class UserController extends app.Controller {
+    fetch* () {


* fetch()

@dead-horse 没改全，搜索下

dead-horse · 2017-05-17T03:04:42Z

fixed

atian25 · 2017-05-17T03:16:16Z

docs/source/zh-cn/basics/objects.md

+// app/controller/user.js
+module.exports = app => {
+  return class UserController extends app.Controller {
+    fetch* () {


@dead-horse 没改全，搜索下

atian25 · 2017-05-17T03:16:29Z

docs/source/zh-cn/basics/objects.md

+
+### 获取方式
+
+最常见的 Context 实例获取方式是在 [Middleware], [Controller] 以及 [Service] 中。[Controller] 中的获取方式在上面的例子中已经展示过了，在 [Service] 中获取和 [Controller] 中获取的方式一样，在 [Middleware] 中获取 Contenxt 实例则和 [koa] 框架在中间件中获取 Context 对象的方式一致。


Contenxt 这个 typo 没改

dead-horse · 2017-05-17T03:40:56Z

额，再看看

atian25

其他 +1，没问题

atian25 · 2017-05-17T03:58:42Z

docs/source/zh-cn/basics/objects.md

+  };
+  ```
+
+和 [koa] 一样，在 Context 对象上，可以通过 `ctx.app` 访问到 Application 对象。以上面的 Controller 文件举例：


这里的链接是不是错了，底部的 [Koa]: 是大写的

atian25 · 2017-05-17T03:58:55Z

docs/source/zh-cn/basics/objects.md

+
+### 获取方式
+
+最常见的 Context 实例获取方式是在 [Middleware], [Controller] 以及 [Service] 中。[Controller] 中的获取方式在上面的例子中已经展示过了，在 [Service] 中获取和 [Controller] 中获取的方式一样，在 [Middleware] 中获取 Context 实例则和 [koa] 框架在中间件中获取 Context 对象的方式一致。


这个 koa 也是

dead-horse · 2017-05-17T04:07:44Z

😢

okoala · 2017-05-17T04:29:59Z

这篇要赞~

popomore · 2017-05-17T04:47:30Z

docs/source/zh-cn/basics/objects.md

+};
+```
+
+在 Controller, Service 类中，可以通过 `this.app` 访问到 Application 对象。


可以提一下这个是 controller 基类定义的，不然分不清 this.app 和 this.ctx.app

改成了 在继承于 Controller, Service 基类的实例中，可以通过 this.app 访问到 Application 对象。

huacnlee · 2017-05-17T07:09:49Z

docs/source/zh-cn/basics/objects.md

+
+## Context
+
+Context 是一个**请求级别的对象**，继承自 [koa.Context]。在每一次收到用户请求时，框架会实例化一个 Context 对象，这个对象封装了这次用户请求的信息，并提供了许多便捷的方法来获取请求参数或者设置响应信息。框架会将所有的 [Service] 挂载到 Context 实例上，一些插件也会将一些其他的方法和对象挂载到它上面（[egg-sequelize] 会将所有的 model 挂载在 Context 上。


[egg-sequelize] 会将所有的 model 挂载在 Context 上

实际不是这样的

ctx.model.User 而不是直接挂的

最终都是�通过 ctx.model 来访问，和 service 一样吧？

huacnlee · 2017-05-17T07:10:04Z

docs/source/zh-cn/basics/objects.md

+
+最常见的 Context 实例获取方式是在 [Middleware], [Controller] 以及 [Service] 中。[Controller] 中的获取方式在上面的例子中已经展示过了，在 [Service] 中获取和 [Controller] 中获取的方式一样，在 [Middleware] 中获取 Context 实例则和 [Koa] 框架在中间件中获取 Context 对象的方式一致。
+
+框架的 [Middleware] 同时支持 koa v1 和 koa v2 两种不同的中间件写法，根据不同的写法，获取 Context 实例的方式也稍有不同：


huacnlee · 2017-05-17T07:10:38Z

docs/source/zh-cn/basics/objects.md

+
+## Request & Response
+
+Request 是一个**请求级别的对象**，继承自 [koa.Request]。封装了 node 原生的 http request 对象，提供了一系列辅助方法获取 HTTP 请求常用参数。


node -> Node.js

http request -> HTTP Request

往后的类似地方也是需要修改

dead-horse added the type: document label May 16, 2017

dead-horse requested review from fengmk2, atian25 and popomore May 16, 2017 04:30

atian25 requested changes May 16, 2017

View reviewed changes

dead-horse added 4 commits May 17, 2017 00:38

docs: add document for built-in objects

20dfe8b

f

c228f1b

f

8db17a2

f

0ab277d

dead-horse force-pushed the objects branch from 7445d4e to 0ab277d Compare May 16, 2017 16:39

atian25 approved these changes May 16, 2017

View reviewed changes

atian25 reviewed May 16, 2017

View reviewed changes

f

99eb6c7

atian25 approved these changes May 17, 2017

View reviewed changes

f

fefb98c

atian25 approved these changes May 17, 2017

View reviewed changes

f

05db134

popomore approved these changes May 17, 2017

View reviewed changes

f

7ad50ad

fengmk2 approved these changes May 17, 2017

View reviewed changes

fengmk2 merged commit fd04ea2 into master May 17, 2017

fengmk2 deleted the objects branch May 17, 2017 06:55

huacnlee reviewed May 17, 2017

View reviewed changes


		## Context

		Context 是一个请求级别的对象，继承自 [koa.Context]。在每一次收到用户请求时，框架会实例化一个 Context 对象，这个对象封装了这次用户请求的信息，并提供了许多便捷的方法来获取请求参数或者设置响应信息。框架会将所有的 [service](./service.md) 挂载到 Context 实例上，一些插件也会将一些其他的方法和对象挂载到它上面（[egg-sequelize] 会将所有的 model 挂载在 Context 上。


		Helper 自身是一个类，有和 [Controller](#controller) 基类一样的属性，它也会在每次请求时进行实例化，因此 Helper 上的所有函数也能获取到当前请求相关的上下文信息。

		### 获取方式


		### 获取方式

		最常见的 context 实例获取方式是在 [Middleware], [Controller] 以及 [Service] 中。[Controller] 中的获取方式在上面的例子中已经展示过了，在 [Service] 中获取和 [Controller] 中获取的方式一样，在 [Middleware] 中获取 Contenxt 实例则和 [koa] 框架在中间件中获取 Context 对象的方式一致。


		## Config

		我们推荐应用开发遵循配置和代码分离的原则，将一些需要硬编码的业务配置都放到配置文件中，同时配置文件支持各个不同的运行环境使用不同的配置，使用起来也非常方便，所有框架、插件和应用级别的配置都可以通过 Config 对象获取到，关于框架的配置，可以详细阅读[Config 配置](./config.md)章节。


		最常见的 Context 实例获取方式是在 [Middleware], [Controller] 以及 [Service] 中。[Controller] 中的获取方式在上面的例子中已经展示过了，在 [Service] 中获取和 [Controller] 中获取的方式一样，在 [Middleware] 中获取 Context 实例则和 [Koa] 框架在中间件中获取 Context 对象的方式一致。

		框架的 [Middleware] 同时支持 koa v1 和 koa v2 两种不同的中间件写法，根据不同的写法，获取 Context 实例的方式也稍有不同：


		## Request & Response

		Request 是一个请求级别的对象，继承自 [koa.Request]。封装了 node 原生的 http request 对象，提供了一系列辅助方法获取 HTTP 请求常用参数。

docs: add document for built-in objects #914

docs: add document for built-in objects #914

Conversation

dead-horse commented May 16, 2017

Checklist

Affected core subsystem(s)

Description of change

mention-bot commented May 16, 2017

codecov bot commented May 16, 2017 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dead-horse commented May 16, 2017

atian25 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dead-horse commented May 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dead-horse commented May 17, 2017

atian25 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dead-horse commented May 17, 2017

okoala commented May 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented May 16, 2017 •

edited

Loading