Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add intro/index.md #246

Merged
merged 4 commits into from
Jan 13, 2017
Merged

docs: Add intro/index.md #246

merged 4 commits into from
Jan 13, 2017

Conversation

popomore
Copy link
Member

@popomore popomore commented Jan 12, 2017

Checklist
  • npm test passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc

Description of change

@popomore popomore added this to the 1.0.0 milestone Jan 12, 2017

egg 的插件机制有很高的定制化,插件只做一件事,比如 nunjucks 模板封装了 [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks),MySQL 数据库封装成了 [egg-mysql](https://github.com/eggjs/egg-mysql)。egg 通过框架聚合这些插件,并根据自己的业务场景定制配置,这样应用的开发成本就变得很低。

egg 奉行「约定优于配置」,按照一定的约定进行应用开发,企业内部采用这种方式可以减少开发人员的学习成本,开发人员不再是「钉子」,可以云动起来。但约定不等于扩展性差,相反 egg 有很高的扩展性,可以定制企业自己的约定。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

一定的约定 指向 loader 那篇文章

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「约定优于配置」

『约定优于配置』

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「钉子」

『钉子』

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

模板封装成了,漏了个字

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「老师,『有条不紊』的『紊』是什么意思?」

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

@atian25 atian25 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

完了?要不要把PPT那张层次图放上来?

Copy link
Member

@atian25 atian25 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

看到 WIP 了

@popomore popomore force-pushed the doc-intro branch 4 times, most recently from d3a0cf6 to 1fe4270 Compare January 12, 2017 16:45
@codecov-io
Copy link

codecov-io commented Jan 12, 2017

Current coverage is 97.93% (diff: 100%)

Merging #246 into master will increase coverage by 0.04%

@@             master       #246   diff @@
==========================================
  Files            34         34          
  Lines           903        969    +66   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits            884        949    +65   
- Misses           19         20     +1   
  Partials          0          0          

Powered by Codecov. Last update e6311ef...c5ea1c9


## 设计原则

egg 是社区少见的一种框架,它并没有集成社区常见的一些功能(诸如数据库、模板引擎、前端框架等),只是提供了 web 开发的核心功能和一套插件机制。为了团队能够基于 egg 扩展自己的框架,我们不会做出技术选型,因为固定的技术选型会让框架过于片面,无法满足的定制需求,egg 可以帮助架构师基于技术选型搭建框架。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

无法满足的定制需求

无法满足各种定制需求

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

egg 可以帮助架构师基于技术选型搭建框架。

egg 可以帮助架构师、技术负责人基于技术选型搭建框架。


egg 是社区少见的一种框架,它并没有集成社区常见的一些功能(诸如数据库、模板引擎、前端框架等),只是提供了 web 开发的核心功能和一套插件机制。为了团队能够基于 egg 扩展自己的框架,我们不会做出技术选型,因为固定的技术选型会让框架过于片面,无法满足的定制需求,egg 可以帮助架构师基于技术选型搭建框架。

egg 的插件机制有很高的定制化,插件只做一件事,比如 nunjucks 模板封装成了 [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks),MySQL 数据库封装成了 [egg-mysql](https://github.com/eggjs/egg-mysql)。egg 通过框架聚合这些插件,并根据自己的业务场景定制配置,这样应用的开发成本就变得很低。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

插件只做一件事

一个插件只做一件事


## 与社区框架的差异

[expressjs] 是 node 社区广泛使用的框架,简单且扩展性强,非常适合做个人项目。但框架本身缺少约定,标准的 MVC 模型会有各种千奇百怪的写法。egg 按照约定进行开发,奉行『约定优于配置』,团队协作成本低。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

express


[expressjs] 是 node 社区广泛使用的框架,简单且扩展性强,非常适合做个人项目。但框架本身缺少约定,标准的 MVC 模型会有各种千奇百怪的写法。egg 按照约定进行开发,奉行『约定优于配置』,团队协作成本低。

[sailsjs] 是和 egg 一样奉行『约定优于配置』的框架,扩展性也非常好。但是相比 egg,[sailsjs]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sails

## 特性

- 深度[框架定制](../advanced/framework.md)
- 高度扩展的[插件机制](../advanced/plugin.md)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

高度可扩展

@popomore popomore force-pushed the doc-intro branch 2 times, most recently from d3317a3 to 272e096 Compare January 13, 2017 02:29
@popomore
Copy link
Member Author

再看看


## 设计原则

egg 是社区少见的一种框架,它并没有集成社区常见的一些功能(诸如数据库、模板引擎、前端框架等),只是提供了 web 开发的核心功能和一套插件机制。为了团队能够基于 egg 扩展出自己的框架,我们不会做出的技术选型,因为固定的技术选型会使框架的扩展性变差,无法满足各种定制需求,egg 可以帮助架构师、技术负责人基于他们的技术选型搭建框架。。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

egg 是社区少见的一种框架,它并没有集成社区常见的一些功能(诸如数据库、模板引擎、前端框架等),只是提供了 web 开发的核心功能和一套插件机制。 为了团队能够基于 egg 扩展出自己的框架,我们不会做出的技术选型,因为固定的技术选型会使框架的扩展性变差,无法满足各种定制需求,egg 可以帮助架构师、技术负责人基于他们的技术选型搭建框架。。

改为:

> think about future, design with flexibility, but only implement for production.

在我们思考 egg 框架的定位时,我们深知企业级应用场景下,在追求规范化,共建复用的同时,还需要考虑如何平衡不同团队之间的差异性,求同存异。

故我们并没有选择社区常见框架的大集市模式(集成如数据库、模板引擎、前端框架等功能),而是专注于提供了 web 开发的核心功能和一套灵活强大的插件机制。

我们不会捆绑技术选型,因为固定的技术选型会使框架的扩展性变差,无法满足各种定制需求。

通过 egg,团队架构师和技术负责人可以非常容易的,基于他们的技术选型,在 egg 之上扩展出适合自己业务场景的框架。

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

think about future, design with flexibility, but only implement for production.

这句出处是哪里?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

之前在内网看到的, 觉得挺不错的

@@ -1,2 +1,31 @@
title: 什么是 egg
---

**egg 为企业级框架和应用而生**,我们希望通过 egg 能孕育更多上层框架帮助开发团队和开发人员。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

我们希望通过 egg 能孕育更多上层框架帮助开发团队和开发人员。 -- 不太通顺

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

我们希望由 egg 孕育出更多上层框架,帮助开发团队和开发人员降低维护成本

怎么样

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

由 egg 孕育 不太对, 应该是他们通过 egg 来...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

有种破壳而出的感觉,不能细想


egg 的插件机制有很高的可扩展性,**一个插件只做一件事**(比如 nunjucks 模板封装成了 [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks)、MySQL 数据库封装成了 [egg-mysql](https://github.com/eggjs/egg-mysql))。egg 通过框架聚合这些插件,并根据自己的业务场景定制配置,这样应用的开发成本就变得很低。

egg 奉行『约定优于配置』,按照[一定的约定](../advanced/loader.md)进行应用开发,团队内部采用这种方式可以减少开发人员的学习成本,开发人员不再是『钉子』,可以云动起来。没有约定的团队,沟通成本是非常高的,比如有人会按目录分栈而其他人按目录分功能,开发者认知不一致很容易犯错。但约定不等于扩展性差,相反 egg 有很高的扩展性,可以按照团队的约定定制框架,使用 [Loader](../advanced/loader.md) 可以按照团队的约定来加载(默认约定也可以覆盖)。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

一定的约定 -> 一套统一的约定


## 与社区框架的差异

[express] 是 node 社区广泛使用的框架,简单且扩展性强,非常适合做个人项目。但框架本身缺少约定,标准的 MVC 模型会有各种千奇百怪的写法。egg 按照约定进行开发,奉行『约定优于配置』,团队协作成本低。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

加上 koa ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

koa 没想好怎么写,跟 express 是一样的

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

就简单介绍下 koa 比起 express 的变化, 然后说明 egg 是在 koa 之上的, 再链接到另一篇文档就好了吧

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

下面特性有介绍,这里介绍其实区别不大

Copy link
Member

@atian25 atian25 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

再加一张图?

+--------------------------------------------------------------------+
|                ali, uc, ant, ... app                    |
+---------+----------------------------------------------------------+
|         |   xxxxx ...   |  +----------------------------------------------------------+
|         |                          egg                             |
+---------+----------------------------------------------------------+
|                          web.md Specification                      |
+--------------------------------------------------------------------+
|                                  koa                               |
+--------------------------------------------------------------------+
|  xxxx ...   |
+--------------------------------------------------------------------+

Advanced:
# Deployment: /advanced/deployment.html
View Plugin: /advanced/view-plugin.html
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

顺便补下 unit test 和 mysql 的链接


[express] 是 node 社区广泛使用的框架,简单且扩展性强,非常适合做个人项目。但框架本身缺少约定,标准的 MVC 模型会有各种千奇百怪的写法。egg 按照约定进行开发,奉行『约定优于配置』,团队协作成本低。

[sails] 是和 egg 一样奉行『约定优于配置』的框架,扩展性也非常好。但是相比 egg,[sails] 支持 blueprint REST API、[WaterLine] 这样可扩展的 ORM、前端集成、WebSocket 等,但这些功能都是由 sails 提供的。而 egg 不直接提供功能,只是集成各种功能插件,比如实现 egg-blueprint,egg-waterline 等这样的插件,再使用 sails-egg 框架整合这些插件就体可以替代 sails 了。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

插件就体可以替代 sails 了

多了一个 体 字


## 设计原则

egg 是社区少见的一种框架,它并没有集成社区常见的一些功能(诸如数据库、模板引擎、前端框架等),只是提供了 web 开发的核心功能和一套插件机制。为了团队能够基于 egg 扩展出自己的框架,我们不会做出的技术选型,因为固定的技术选型会使框架的扩展性变差,无法满足各种定制需求,egg 可以帮助架构师、技术负责人基于他们的技术选型搭建框架。。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

结尾两个句号

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

咦, 我那段怎么不见了?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

egg 是社区少见的一种框架,它并没有集成社区常见的一些功能(诸如数据库、模板引擎、前端框架等),只是提供了 web 开发的核心功能和一套插件机制。 为了团队能够基于 egg 扩展出自己的框架,我们不会做出的技术选型,因为固定的技术选型会使框架的扩展性变差,无法满足各种定制需求,egg 可以帮助架构师、技术负责人基于他们的技术选型搭建框架。。

改为:

> think about future, design with flexibility, but only implement for production.

在我们思考 egg 框架的定位时,我们深知企业级应用场景下,在追求规范化,共建复用的同时,还需要考虑如何平衡不同团队之间的差异性,求同存异。

故我们并没有选择社区常见框架的大集市模式(集成如数据库、模板引擎、前端框架等功能),而是专注于提供了 web 开发的核心功能和一套灵活强大的插件机制。

我们不会捆绑技术选型,因为固定的技术选型会使框架的扩展性变差,无法满足各种定制需求。

通过 egg,团队架构师和技术负责人可以非常容易的,基于他们的技术选型,在 egg 之上扩展出适合自己业务场景的框架。


egg 的插件机制有很高的可扩展性,**一个插件只做一件事**(比如 nunjucks 模板封装成了 [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks)、MySQL 数据库封装成了 [egg-mysql](https://github.com/eggjs/egg-mysql))。egg 通过框架聚合这些插件,并根据自己的业务场景定制配置,这样应用的开发成本就变得很低。

egg 奉行『约定优于配置』,按照[一套统一的约定](../advanced/loader.md)进行应用开发,团队内部采用这种方式可以减少开发人员的学习成本,开发人员不再是『钉子』,可以云动起来。没有约定的团队,沟通成本是非常高的,比如有人会按目录分栈而其他人按目录分功能,开发者认知不一致很容易犯错。但约定不等于扩展性差,相反 egg 有很高的扩展性,可以按照团队的约定定制框架,使用 [Loader](../advanced/loader.md) 可以按照团队的约定来加载(默认约定也可以覆盖)。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

可以讲讲每个插件、框架都可以有自定义不同环境的默认配置作为约定(例如 static 默认配置不缓存便于修改,线上环境缓存提升性能,应用开发者完全不用关心,直接开发就可以)?

@fengmk2
Copy link
Member

fengmk2 commented Jan 13, 2017

@atian25 https://eggjs.org/zh-cn/advanced/loader.html 这里有更加准确的图

@popomore
Copy link
Member Author

再看看,这个图就不加了

@dead-horse
Copy link
Member

LGTM, WIP 的 label 可以去掉了?

Security: /core/security.html
# Passport: /core/passport.html
HttpClient: /core/httpclient.html
Logger: /core/logger.html
Error Handling: /core/error-handling.html
i18n: /core/i18n.html
View: /core/view.html
Unittest: /core/unittest.html
Copy link
Member

@atian25 atian25 Jan 13, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unit Test?

@@ -30,13 +30,18 @@ guide_toc:
Schedule: 定时任务
Extend: 框架扩展
Custom init: 启动自定义
Development: 本地开发
Unittest: 单元测试
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unit Test

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


egg 的插件机制有很高的可扩展性,**一个插件只做一件事**(比如 [nunjucks] 模板封装成了 [egg-view-nunjucks](https://github.com/eggjs/egg-view-nunjucks)、MySQL 数据库封装成了 [egg-mysql](https://github.com/eggjs/egg-mysql))。egg 通过框架聚合这些插件,并根据自己的业务场景定制配置,这样应用的开发成本就变得很低。

egg 奉行『**约定优于配置**』,按照[一套统一的约定](../advanced/loader.md)进行应用开发,团队内部采用这种方式可以减少开发人员的学习成本,开发人员不再是『钉子』,可以云动起来。没有约定的团队,沟通成本是非常高的,比如有人会按目录分栈而其他人按目录分功能,开发者认知不一致很容易犯错。但约定不等于扩展性差,相反 egg 有很高的扩展性,可以按照团队的约定定制框架。使用 [Loader](../advanced/loader.md) 可以让框架根据不同环境定义默认配置,还可以覆盖 egg 的默认约定。
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

其他地方都是 「」 都统一这个好点吧? 知乎也是推荐用这个.
cc @fengmk2

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

我 review 的都是用的 『』

@atian25
Copy link
Member

atian25 commented Jan 13, 2017

其他 +1

@popomore popomore removed the WIP label Jan 13, 2017
Copy link
Member

@atian25 atian25 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@fengmk2 fengmk2 merged commit a4f3859 into master Jan 13, 2017
@fengmk2 fengmk2 deleted the doc-intro branch January 13, 2017 06:53
@fengmk2
Copy link
Member

fengmk2 commented Jan 13, 2017

💯 文档第一个里程碑达成

mattma added a commit that referenced this pull request Jan 17, 2017
* master: (37 commits)
  docs: fix quickstart typo (#266)
  docs: add http client debug docs (#265)
  docs: modify and fix 3 points (#264)
  docs(intro): improve decription (#263)
  docs: fix docs site version (#262)
  docs: Fix typo.  (#261)
  docs: review 1st version docs (#257)
  fix: typo conext -> context (#259)
  docs: contributing && readme && deps (#253)
  docs: fix quickstart link in index.html (#256)
  docs: set the default locale zh-cn (#255)
  refactor: ctx.realStatus delegate ctx.response.realStatus (#252)
  docs: Add intro/index.md (#246)
  feat: adjust default plugins (#251)
  docs: add RESTful documents (#247)
  feat: delegate ctx.jsonp to ctx.response.jsonp (#248)
  chore: remove examples (#245)
  docs: improve mysql doc
  docs: add mysql doc
  docs: view (#228)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants