https://github.com/dvajs/dva-knowledgemap

https://mcollina.github.io/the-cost-of-logging/

https://nodejs.org/api/console.html#console_new_console_stdout_stderr

Console is a class.

增加不同类别的 label

1. semver: major, semver: minor, semver: patch
2. core
3. plugin: security,
4. tools: egg-mock, egg-bin
5. feature, fix, refactor, improve, test, doc, release, discussion

关于 loader 有几个问题，需要先确定下

• 运行环境及其名称，是否还是这几个 prod, test, default, local, unittest ？
• 运行环境如何确定，除了 process.env.NODE_ENV
• 是否还需要支持 framework 封装这个功能？

先想到这些，后面有再补充

badgeboard 面板上能加上各个组件的说明么？

Core

• egg @fengmk2
• egg-loader @gxcsoccer
• egg-logger @fengmk2
• egg-cluster @dead-horse
• egg-cookies @fengmk2

Tool

• egg-mock @popomore
• egg-bin @fengmk2
• egg-init @fengmk2

Plugin

• onerror @dead-horse
• userservice @shaoshuai0102
• userrole @atian25
• session @dead-horse
• i18n @gxcsoccer
• validate @dead-horse
• watcher @luckydrq
• multipart @gxcsoccer
• security @jtyjty99999
• development @jtyjty99999
• rest @shaoshuai0102
• static @dead-horse
• cors @dead-horse
• logrotater @jtyjty99999
• schedule @dead-horse
• view-nunjucks @@atian25

framework

• aliyun-egg

Doc

• egg README
• 其他 README 规范
• CONTRIBUTING
• Tutorial
• benchmark @fengmk2

release ready

• session 需要优化，支持非 cookie 存储 koajs/session#66

开发方式

1. 先提交源码保证可以用，依赖层级比较深。
2. 补测试，测试的目录接口和源码保持一致。
3. 新仓库先提交空的 README，提交 PR 完成功能，补测试需要测试通过

我们大多数业务都是基于数据库操作，希望官方能提供一个基于数据库的标准CRUD操作例子，大家通过标准example比较容易上手，感谢;

给 example 加上测试，CI 里面跑一下，保证示例的正确性。

• egg-proxymock -> egg-mockdata ?
• 配合 loader #11 的改造, 支持 mock 不同的对象
• 除了原支持的 exports.fn 方式, 增加 class 的支持, 如继承 ServiceClass 然后替换

在 strict 模式下部分验证将 warn 改成 error

类似 oss / mysql 等都可能存在需要创建多个实例的需求，在插件里面现在有两种实现方式：

1. 新增一个 createInstance 方法来自定义创建。
2. 配置支持数组形式，然后通过 this.mysql.db1 来获取

对外的插件最好有一个统一的形式。特别是 aliyun-egg 估计会遇到挺多类似的问题

alinode won't delete the log files, egg-alinode plugin should delete 7 days ago log files.

Here are a few ideas for the Egg.js framework slogan

1. A supreme node.js framework builder to maximize productivity
2. A modular framework builder for node.js developer
3. The last node.js framework you ever need
4. The node.js framework changes everything
5. A promise to your success
6. A node.js framework Builder
7. next generation web framework builder for node.js (Note: compared with http://koajs.com/ slogan)
8. Modular, opinionated, feature rich web framework for Node.js (Note: compared with http://expressjs.com/ slogan)

• egg-init 自己的单元测试 eggjs/egg-init#15
• 做个 mocha 的插件, 自动根据 boilerplate 生成示例, 并跑示例的单元测试?
  • eggjs/egg-boilerplate-simple#15
  • eggjs/egg-boilerplate-plugin#8
  • eggjs/egg-boilerplate-framework#3
  • eggjs/egg-boilerplate-empty#1

刚看了 Singleton 的文档, 有几点疑问, 讨论下:

• 我们之前的实现里面, 有很多用 Symbol + this[HELPER] 之类的方式去实现只实例化一次的对象, 这个是不是可以类似提供下简化方法?
• 是否要考虑 loader singleton 的约定?
• Singleton 其实是支持多实例的,那这个命名是不是不太准确?
• 示例里面的 DataService 这个命名感觉有点问题, 会认为是放在 app/service 下, 但这个就是每个请求一个实例了.

use agentx and commandx

https://github.com/eggjs/egg/blob/master/lib/core/app/extend/context.js#L207

方便获取自定义 logger，并且自动填充 ctx 信息，就如 ctx.logger 一样。

• http://jaysoo.ca/2014/03/20/i18n-with-es6-template-strings/
• https://www.npmjs.com/package/common-tags

{{ i18nHello ${user.name}, how are you today?}}

master 现在的 loader 会加载 config

1. 读取 env，可以单独实现
2. 获取 logger 的配置，master 的 logger 可以直接使用 consoleLogger，error 打到 stderr

• CONTRIBUTING.md
• README.md 语法。。
• web.md 地址在内网

把这个更新到文档里，作为一个规范

• 介绍 intro
  • 什么是 egg（是什么，解决什么问题，egg 重要特性，cluster，插件机制） #246 @popomore
  • 基于 koa（介绍 koa，并介绍做了什么扩展） #179 @dead-horse
  • hello world 快速上手（给一个 example 链接，解读代码，过一下 egg 基本功能） #217 @atian25
• 功能详解 basics（只有 app，感知不到 agent）
  • env（默认环境，自定义环境） #178 @popomore
  • config（根据环境加载，顺序，appInfo，如何获取）#188 @popomore
  • middleware（koa 中间件，参数，中间件顺序）#194 @dead-horse
  • router @leoner （路由规则，原则，API）#203
  • controller（controller, session ...）#209 @dead-horse
  • service #221 @leoner
  • schedule @dead-horse #202
  • extend（extend koa api，加载顺序） #187 @shaoshuai0102
  • 启动自定义（app.js）#193 @shaoshuai0102
• 核心功能（内置插件功能） core
  • security（安全介绍） #196 @jtyjty99999
  • passport/userservice
  • userrole @gxcsoccer
  • tracer @fengmk2
  • httpclient #197 @fengmk2
  • 日志（logrotator，logger，自定义，transport）#204 @shaoshuai0102
  • 异常处理 @dead-horse
  • i18n #208 @shaoshuai0102
  • 本地开发和 debug #214 @shaoshuai0102
  • 应用单元测试（用例写法，常用工具介绍，egg-mock） #199 @fengmk2
• 最佳实践 practice
  • view and assets（介绍 egg-view-nunjucks，如何使用 view，自定义 view，静态文件的例子） #228 @atian25
  • 访问 MySQL #234 @jtyjty99999
  • 实现 RESTful API #247 @dead-horse
  • 渐进式开发, 介绍 app -> plugin -> framework 的演变 #268 @atian25
• 高级功能 advanced
  • 部署（构建打包，install-node，环境依赖，部署，可以添加一个 docker 的例子）
  • cluster 模式，客户端规范（cluster-client，这里引入 agent 概念）#191 @gxcsoccer
  • 开发插件（包括插件原理）#224 @gxcsoccer
  • 开发框架（框架继承，如何扩展，原理） #225 @popomore
  • 加载器（加载顺序，自定义加载） #198 @popomore

• Symbol 的命名规则
• config.default.js 的 jsdoc 规则

分布式链路追踪是当今微服务架构中必不可少的组成部分，一个请求穿插于各个应用系统、中间件、数据库之间，通过 tracing 就能知道整个请求的链路以及各部分的耗时。Egg 会基于开放的 opentracing 来实现这个功能。

概念

Trace：一个 Trace 代表在微服务架构中的一次链路请求，可能经过一个或多个微服务应用。

Span：一个 span 代表系统中具有开始时间和执行时长的逻辑运行单元，一个 Trace 会包含多个 Span。

SpanContext：代表一个 Span 的信息，比如 TraceId，spanId，以及该 Span 的相关信息。注意：这个和 egg 的 ctx 没有关系。

Baggage：还有一些信息也在 SpanContext 中，我们称之为 Baggage，这些信息会在整个 Trace 中传递。

Tag：Span 中用来识别 span 的一些信息，比如

• error
• component: httplib, jdbc, mongoose
• span.kind: client, server
• http.url
• http.method
• http.status_code
• framework
• peer.hostname

Carrier：在微服务架构中，两个应用之前会通过不同的协议进行通讯，但是 opentracing 是无法感知的，所以定义了 Carrier 这个概念，他通过 Inject 和 Extract 和 SpanContext 之前进行互相转换，然后 Carrier 可以在协议中传递。比如 HTTP 请求，SpanContext 通过 Inject 设置 HTTPCarrier（转换成请求头），在请求接收方通过 Extract 将 HTTPCarrier 提取成 SpanContext。

Collector：我们通过 Collector 收集每个 span 的具体信息，然后记录，可以通过日志的方式或请求上报的方式。

实现方案

Egg 提供 ctx.tracer 实例作为一次 Trace，下面按照一个微服务应用整个请求周期描述各个 API

接收请求

比如收到了一个 HTTP 请求，在 server 入口应该

// app/middleware/meta.js
module.exports = () => {
  return async function meta(ctx, next) {
    // 从 http header 获取 span 上下文
    const spanContext = ctx.tracer.extract('HTTP', ctx.header);
    // 创建 span 时指定父级 span
    const span = ctx.tracer.startSpan('http_server', { childOf: spanContext });
    await next();
    span.finish();
  };
}

const span = ctx.tracer.startSpan('rpcclient');
const rpcCarrier = {};
ctx.tracer.inject(span.context, 'RPC', rpcCarrier);
ctx.rpcclient.invoke(data, rpcCarrier);
span.finish();

// lib/http_carrier.js
module.exports = class HttpCarrier {
    
  inject(spanContext) {
    // 转换
    return header;
  }
  
  extract(header) {
    // 转换
    return spanContext;
  }
  
}

// config/config.default.js
exports.opentracing = {
  carrier: {
    'HTTP': require('../lib/http_carrier'),
  },
};

// lib/log_collector.js
module.exports = class LogColletor {
    
  collect(spanContext) {
    this.ctx.logger.write(this.format(spanContext));
  }

}

// config/config.default.js
exports.opentracing = {
  collector: {
    log: require('../lib/log_collector'),
  },
};

// config/config.default.js
exports.opentracing = {
  globalTracer: YourTracer,
};

提供方法：

1. broadcast(action, data)：发送给所有的 agent / app 进程（包括自己）
2. sendToApp(action, data): 发送给所有的 app 进程
   • 在 app 调用该方法上会发送给自己和其他的 app 进程
   • 在 agent 上调用该方法会发送给所有的 app 进程
3. sendToAgent(action, data): 发送给 agent 进程
   • 在 app 调用该方法上会发送 agent 进程
   • 在 agent 上调用该方法会发送给 agent 自己
4. sendRandom(action, data):
   • app 上没有该方法（现在 egg 的实现是等同于 sentToAgent）
   • agent 上回随机发送消息给一个 app 进程（由 master 来控制发送给谁）
5. sendTo(pid, action, data): 发送给指定进程

egg-mock is a mock server and a list of mocked API with egg-mock plugin.

• mm.app
• mm.cluster
• API
• test with egg

我们是大写分隔，如果是类就首字母大写还是下划线分隔？

https://github.com/eggjs/egg-bin/blob/master/lib/Command.js

Running cookie example, I clicked on "remember" checkbox, then submit. It routes to /remember route, none of the logic in remember route is being run due to error secret is missing. See the full error log

2016-08-11 23:52:47,376 INFO 10862 [-/::1/-/8ms GET /] status 200 (rt: 8ms)
2016-08-11 23:52:49,389 WARN 10862 [-/::1/-/15ms POST /remember] nodejs.ForbiddenError: secret is missing
    at Object.module.exports.throw (/Users/mattma/Desktop/egg/egg/node_modules/koa/lib/context.js:91:23)
    at Object.context.assertCSRF.context.assertCsrf (/Users/mattma/Desktop/egg/egg/node_modules/koa-csrf/index.js:69:30)
    at Object.csrf (/Users/mattma/Desktop/egg/egg/node_modules/egg-security/lib/middlewares/csrf.js:39:12)
    at next (native)
    at Object.<anonymous> (/Users/mattma/Desktop/egg/egg/node_modules/koa-compose/index.js:29:12)
    at next (native)
    at onFulfilled (/Users/mattma/Desktop/egg/egg/node_modules/co/index.js:65:19)
    at /Users/mattma/Desktop/egg/egg/node_modules/co/index.js:54:5
    at Object.co (/Users/mattma/Desktop/egg/egg/node_modules/co/index.js:50:10)
    at Object.toPromise (/Users/mattma/Desktop/egg/egg/node_modules/co/index.js:118:63)

方便有问题的用户提交 issue

https://github.com/eggjs/egg/pull/7/files#diff-1a1c3dd142f76a5fad803a0c52839881R15

Loader

做到灵活性，扩展性强。

API

loader 只提供原子粒度的 API，由框架来自行组织

Env

• getServerEnv
• getEggPaths
• getLoadUnits
• getAppname

Low Level API

• loadFile
• loadToApp
• loadToContext
• loadExtend

High Level API

• loadPlugin
• loadConfig
• loadController
• loadMiddleware
• loadApplicationExtend
• loadContextExtend
• loadRequestExtend
• loadResponseExtend
• loadHelperExtend
• loadCustomApp
• loadCustomAgent
• loadService

和插件的关系

插件需要用到 loader 功能需要增加一个 loader 插件，比如 db 的功能

|- app
  `- db
    `- a.js

// app.js
module.exports = function(loader) {
  app.loader.loadToApp('app/db', 'db');
};

|- app
  |- extend
  |- service
  |- controller
  |- middleware
  `- router.js
|- config
  |- config.js
  `- plugin.js
|- agent.js
`- app.js

this.db.xxx -> app/db/xxx.js
this.filters.xxx -> app/filters/xxx.js

将现有用到的术语整理出来，保持统一，写文档和代码都好理解

背景

Egg 参与人员过多，仓库过多，经常会遇到某个人没有某仓库的发布权限。

Release 时会修改版本和更新 changelog，这个也需要 review。

目标

1. Changelog 可 review
2. npm 自动发布
3. 锁定 master 目录不允许提交

方案

锁定 master 目录不允许任何人提交，并添加合并检测（review+2，travis 和 codecov 通过）。

Release 时本地修改版本和 changelog 后提交 PR，review 后合并。

Travis 根据 commit 信息判断是否 release（非 PR，master 分支，切 commit 匹配），通过 eggjs 账号 发布到 npm。

Action

• 支持 travis 发布 npm 包，还需要自动 push tag
• “本地生成 changelog 和版本”有工具支持，保证生成格式一致
• 文档更新
• 确定 commit 信息 chore(release): release 1.0.0
• 自动更新 github release

Updated at 2017-02-09

以后所有的仓库都需要这样配置，不允许直接 push 到 master。但是 release 的时候还有一步需要 push，这个规则需要明确下。

schedule 的结构是

{
  'filepath': exports
}

Features

• dev
• test
• cov
• debug
• stc

Custom command

• jars
• proxy

deps

• egg-ci
• egg-dependencies

在 Github 如何使用 puml

看能否作为 transport 基类

https://github.com/mcollina/pino

egg与微信集成有plugin么？ 希望提供，感谢

通用安全插件、阿里云各服务插件（oss、cdn、等等常用的） @fishbar

• egg-oss
• egg-rds -> egg-mysql
• egg-security
• mts
• ots
• mc
• ons

待补充

• 构建提交到 gh-pages
• master 分支才构建

• egg-passport-github
• egg-passport-weibo @shaoshuai0102
• egg-passport-gitlab
• egg-passport-google
• egg-passport-taobao

RFC: passport

由于业界的 passport 已经足够简单，egg 做起来就是配置。对应应用开发者，更加是配置，基本无需编写代码就能实现。

一个应用的 authenticate 通用过程

1. 用户会选择应用提供的其中一种 strategy 进行 authenticate 登录，如应用同时提供了 twitter 和 facebook 两种方式。
2. 用户去 twitter 登录成功后，会返回应用网站，然后 egg-passport-twitter 插件，会使用 verify callback 来完成对统一约定 user 的封装，继续返回给 egg-passport 做后续处理。
3. egg-passport 会触发 app.passport.verify hook，这样应用层就能做最终的核实，例如做新用户注册，老用户绑定校验等等，这里也是用户数据持久化的地方。
4. 用户登录之后，每次访问应用都会根据 app.passport.deserializeUser 和 app.passport.serializeUser 来还原 session。

说明

• 框架内置了高度抽象的 passport 插件。
• passport-xxx 插件都需要声明依赖内置的 passport 插件。
• passport-xxx 插件开发者只需要简单结合一下 http://passportjs.org 现有的模块，就可以快速完成一个网站的 authenticate 接入。
  如要对接 Twitter 的 oauth，那么只需要引入 passport-twitter，并实现一个 passport-twitter 插件即可。

统一 user 字段约定

ctx.user 是一个 getter，真实数据来自于 ctx.state.user。

每个 passport-xxx 插件都需要按照约定封装一个 user。

• 必须 user.provider: 用户信息来自那种登录策略，如 twitter, weibo, facebook，这样就能通过此字段读取 user.profile 信息了。一般都是自动填充
• 必须 user.id: 用户 id，字符串
• 必须 user.name: 用户名
• 可选 user.displayName: 昵称
• 可选 user.token: oauth1 的话必须提供
• 可选 user.tokenSecret: oauth1 的话必须提供
• 可选 user.accessToken: oauth2 的话必须提供
• 可选 user.refreshToken: oauth2 的话必须提供
• 可选 user.profile: profile 的其他字段，每个平台提供的都不太一样，需要各种区别

passport 配置

// config/config.${env}.js
exports.passport = {
  twitter: {
    consumerKey: 'your-consumer-key',
    consumerSecret: 'your-consumer-secret',
    // 更多配置请查看 passport-twitter 插件
  },
};

// app.js
module.exports = app => {
  // 1. 核实登录用户信息，自行判断是否需要做数据调整，
  // 也可以在这里由应用自身统一 user 的数据结构，并且保存到数据库。
  // - 必须返回核实后的 user，即 verifiedUser，数据结构可以由应用自行统一约定
  // - 核实失败，throw 一个带有 status = 401 的 error 异常
  // - 其他异常，将会当作服务端内部异常处理
  //
  // passport-xxx 插件已经按约定生成了 user 数据，应用可以在此做最终的用户校验，并且做数据持久化
  // 在 strategy.authenticate 成功之后调用
  app.passport.verify(function* (ctx, user) {
    
  });
  
  // 自行处理经过 verify 后的 verifiedUser 数据如何序列化到 session
  // 在 http 请求结束阶段，保存数据到 session 之前调用
  app.passport.serializeUser(function* (ctx, verifiedUser) {
    // you can store profile and handle token here
  });
  
  // 根据 sesssion 中的 sessionUser 信息，还原出 verifiedUser
  // 在 http 请求开始阶段，还原 session 之后调用
  app.passport.deserializeUser(function* (ctx, sessionUser) {

  });
};

• core
• tests
• docs

大部分都叫 logrotator，而我们是 logrotater

https://www.google.com/search?newwindow=1&safe=off&q=logrotator&oq=logrotator&gs_l=serp.3..0i19k1l2j0i30i19k1j0i10i30i19k1j0i30i19k1j0i10i30i19k1j0i5i30i19k1l4.3911.6739.0.8980.4.4.0.0.0.0.579.1076.4-1j1.2.0....0...1c.1.64.serp..2.2.1075...0.tqTLggRrpXI

https://github.com/eggjs/egg-logrotater

做下备忘, 然后定下时间点和分猪肉吧.

我们还剩下不到 15 天了, 包括周六日.

• 类库
  • 完成 egg 的所有核心库
  • egg 插件检查 (文档, 注释英文, 更新依赖版本, 发布 1.x 版本, public ) #5
  • 框架
    • aliyun-egg 还搞么?
  • example
• 数据收集 @fengmk2 @gxcsoccer
  • benchmark
  • 业务使用情况统计, 应用数/进程数 (先放到内网 issue, 并走数据披露流程)
• 文档编写
  • 编写使用文档, 参考 chair 文档
    • 列出大纲 (#55) @atian25
    • 术语整理
    • 文档列表(待分猪肉)
  • 文档翻译为 English @mattma
  • Web 规范文档的翻译 @mattma
    • 是否需要补充 logger 的规范进去?
    • #12
  • Api 文档构建 #34
  • jsconf ppt 编写 ( @atian25 本周出大纲 review )
• 官网建设 (已出原型图, 使用 hexo 发布, @popomore)
• 清理 milestone, #5

cc @eggjs/core @eggjs/contributor

使用 https://github.com/istanbuljs/nyc 替换 istanbul

Goal: Egg works as simple RESTful api server, Frontend communicates with Egg via Ajax requests. Browser (Chrome latest) has Cross Origin enabled by default. Egg enabled CORS, frontend sends a request and need to get the payload back from Egg.

I have created an Angular frrontend and trying to talk to Egg ONLY via RESTful api. But I run into an issue of CORS. This is the error message from browser console:

XMLHttpRequest cannot load http://localhost:7001/api/user. Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:63342' is therefore not allowed access.

I am not sure that it is an error from front end, or egg, or its plugins: egg-rest, egg-cors, or just an User error.

Here is how you can duplicate the issue.

1st Use [examples/restful_api] , then enabled cors plugins at [here](https://github.com/eggjs/egg/tree/master/examples/restful_api)(https://github.com/eggjs/egg/blob/master/examples/restful_api/config/plugin.js#L3)

// restful_api/config/plugin.js
exports.cors = true;
exports.rest = true;

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
</head>
<body>
  <script>
    jQuery.ajax({
      url: "http://localhost:7001/api/user",
      type: "GET",
      contentType: "application/json",
      async: true,
      crossDomain: true,
      beforeSend: function(xhr) {
        xhr.setRequestHeader('X-Test-Header', 'test-value');
      },
      success: function( users ) {
        console.log('users: ', users)
      }
    });
  </script>
</body>
</html>