docs: add mysql doc #234

jtyjty99999 · 2017-01-11T06:32:28Z

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

fengmk2 · 2017-01-11T06:35:01Z

@mansonchor 来看看？

fengmk2 · 2017-01-11T06:35:39Z

docs/source/zh-cn/practice/mysql.md

+
+# 访问 MySQL 实现数据库操作 
+
+在 WEB 应用方面 MySQL 是最常见，最好的关系型数据库之一。包括阿里巴巴在内，很多网站的开发都选择 MySQL 作为网站数据库。本篇文档介绍了如何使用 egg 框架及其插件来访问数据库。


文档里面统一写 web

包括阿里巴巴在内，很多网站的开发都选择 MySQL 作为网站数据库。

去掉阿里巴巴好了。

非常多网站会选择 MySQL 作为网站数据库。

fengmk2 · 2017-01-11T06:38:55Z

docs/source/zh-cn/practice/mysql.md

+
+在 WEB 应用方面 MySQL 是最常见，最好的关系型数据库之一。包括阿里巴巴在内，很多网站的开发都选择 MySQL 作为网站数据库。本篇文档介绍了如何使用 egg 框架及其插件来访问数据库。
+
+## egg-MySQL


呃。。。这个就写 egg-mysql

fengmk2 · 2017-01-11T06:39:21Z

docs/source/zh-cn/practice/mysql.md

+
+## egg-MySQL
+
+我们提供了 [egg-MySQL](https://github.com/eggjs/egg-mysql)插件来访问 MySQL 数据库，这个插件既可以访问普通的 MySQL 数据库，也可以访问阿里云提供的在线数据库服务 [RDS](https://www.aliyun.com/product/rds?spm=5176.8142029.388261.35.puj0DS)（ApsaraDB for RDS，简称RDS）。


不需要给阿里云打广告，去掉吧

这个插件既可以访问普通的 MySQL 数据库，也可以访问阿里云提供的在线数据库服务

这个插件既可以访问普通的 MySQL 数据库，也可以访问基于 MySQL 协议的在线数据库服务

fengmk2 · 2017-01-11T06:40:30Z

docs/source/zh-cn/practice/mysql.md

+
+## 安装与配置
+
+### 安装插件


安装不需要写了，只需要提示在 package.json 里面依赖这个模块

fengmk2 · 2017-01-11T06:41:06Z

docs/source/zh-cn/practice/mysql.md

+      // 数据库名
+      database: 'test',
+    },
+    // ...


db2 的配置示例也加上

codecov-io · 2017-01-11T07:40:31Z

Current coverage is 97.54% (diff: 100%)

No coverage report found for master at d63752e.

Powered by Codecov. Last update d63752e...fb3d561

atian25 · 2017-01-11T08:29:39Z

docs/source/zh-cn/practice/mysql.md

+title: MySQL
+---
+
+# 访问 MySQL 实现数据库操作 


title 和第一个 # 应该同名吧?

现在不需要再正文中写标题了，所有的章节从 h2 开始

atian25 · 2017-01-11T08:30:21Z

docs/source/zh-cn/practice/mysql.md

+
+## egg-mysql
+
+我们提供了 [egg-mysql](https://github.com/eggjs/egg-mysql)插件来访问 MySQL 数据库。这个插件既可以访问普通的 MySQL 数据库，也可以访问基于 MySQL 协议的在线数据库服务。


插件来访问 前面加个空格

atian25 · 2017-01-11T08:30:39Z

docs/source/zh-cn/practice/mysql.md

+
+## 安装与配置
+
+在 package.json 里面依赖 egg-MySQL模块，并通过 `config/plugin.js` 配置启动 MySQL 插件:


egg-MySQL -> egg-mysql

建议不要直接让用户写 pkg, 提供:

$ npm i egg-mysql --save

参考下 quickstart

atian25 · 2017-01-11T08:33:13Z

docs/source/zh-cn/practice/mysql.md

+
+下面是一个 service 中访问 MySQL数据库的例子。
+
+更多 service 层的介绍，可以参考 egg 文档中的 service 一节。


egg 文档中的 service 一节。 -> [service](../basics/service.md)

atian25 · 2017-01-11T08:33:27Z

docs/source/zh-cn/practice/mysql.md

+
+更多 service 层的介绍，可以参考 egg 文档中的 service 一节。
+
+```javascript


统一用 js

atian25 · 2017-01-11T08:33:51Z

docs/source/zh-cn/practice/mysql.md

+module.exports = app => {
+  class User extends app.Service {
+    // 默认不需要提供构造函数。
+    // constructor(ctx) {


这段不需要了, 这里不是演示 service

atian25 · 2017-01-11T08:34:24Z

docs/source/zh-cn/practice/mysql.md

+
+    * find(uid) {
+      // 假如 我们拿到用户 id 从数据库获取用户详细信息
+      const user = this.app.mysql.query(`select * from user where uid = ${uid}`);


不需要 yield ?

atian25 · 2017-01-11T08:35:00Z

docs/source/zh-cn/practice/mysql.md

+
+之后可以通过 controller 获取 service 层拿到的数据。
+
+```javascript


atian25 · 2017-01-11T08:36:54Z

docs/source/zh-cn/practice/mysql.md

+
+因此，对于一个事务来讲，一定伴随着 beginTransaction, commit 或 rollback ，分别代表事务的开始，成功和失败回滚。
+
+egg-MySQL 提供了两种类型的事务。


egg-mysql, 其他地方也查下

mansonchor · 2017-01-11T06:44:30Z

docs/source/zh-cn/practice/mysql.md

+    // 用户名
+    user: 'test_user',
+    // 密码
+    password: 'test_password',


插件好像有个 encryptPassword 属性，开源的这个还有保留么？

这对密码安全保证比较有好处

@mansonchor 去掉了

mansonchor · 2017-01-11T07:11:37Z

docs/source/zh-cn/practice/mysql.md

+const post = yield this.app.mysql.get('posts', { id: 12 }); // 在 post 表中，搜索 id 为 12 的记录 
+// 查询
+const results = yield this.app.mysql.select('posts',{ // 搜索 post 表
+  where: { status: 'draft' }, // 条件 : status 为 draft


感觉 Read 这个操作介绍有点简单，其实 select 这个方法下的每个字段都可以单独介绍一些最佳实践和例子

例如 where，是支持 WHERE IN 语法糖的

// same like "WHERE status IN('draft', 'pass')" where: { status: ['draft', 'pass'] }

不过不知道这种介绍是放到 egg-mysql 插件的文档里，还是放这里比较好？ @fengmk2

应用层开发需要了解的知识都在这里写完

那就在这里补上，如果今天来不及完善我之后再补 PR

mansonchor · 2017-01-11T09:02:20Z

docs/source/zh-cn/practice/mysql.md

+// if error throw on scope, will auto rollback
+```
+
+## 乐观锁与悲观锁


如果不是框架本身控制这个事情

这个介绍是否没有必要可以去掉？

dead-horse · 2017-01-11T09:31:15Z

docs/source/zh-cn/practice/mysql.md

+
+## 安装与配置
+
+在 package.json 里面依赖 egg-MySQL模块，并通过 `config/plugin.js` 配置启动 MySQL 插件:


egg-mysql 模块

直接写出来吧:

{ "dependencies": { "egg-mysql": "^1.0.1" } }

dead-horse · 2017-01-11T09:35:42Z

docs/source/zh-cn/practice/mysql.md

+
+    * find(uid) {
+      // 假如 我们拿到用户 id 从数据库获取用户详细信息
+      const user = this.app.mysql.query(`select * from user where uid = ${uid}`);


不要在例子里面自己拼 sql！教坏新手

而且要在文档中强调一下，写 sql 时的注意事项，怎么样防止 sql 注入

dead-horse · 2017-01-11T09:37:24Z

docs/source/zh-cn/practice/mysql.md

+};
+```
+
+## 异步处理


异步处理与 mysql 插件没有太大关系吧？

dead-horse · 2017-01-11T09:44:05Z

docs/source/zh-cn/practice/mysql.md

+
+## 直接执行 sql 语句
+
+插件本身也支持拼接与直接执行 sql 语句。使用 `query` 可以执行合法的 sql 语句。


强调不允许自己拼 sql，有什么危害

dead-horse · 2017-01-11T17:54:32Z

docs/source/zh-cn/practice/mysql.md

+// if error throw on scope, will auto rollback
+```
+
+## 乐观锁与悲观锁


乐观锁和悲观锁没必要在这里说吧

mansonchor · 2017-01-12T03:58:52Z

@jtyjty99999 提的建议还在修改么？

fengmk2 · 2017-01-12T07:12:18Z

docs/source/zh-cn/practice/mysql.md

+
+我们提供了 [egg-mysql](https://github.com/eggjs/egg-mysql) 插件来访问 MySQL 数据库。这个插件既可以访问普通的 MySQL 数据库，也可以访问基于 MySQL 协议的在线数据库服务。
+
+## 安装与配置


### 安装与配置

fengmk2 · 2017-01-12T07:12:37Z

docs/source/zh-cn/practice/mysql.md

+};
+```
+
+在 `config/config.${env}.js` 配置各个环境的数据库连接信息：


接信息：

接信息。

fengmk2 · 2017-01-12T07:13:02Z

docs/source/zh-cn/practice/mysql.md

+
+#### 单数据源
+
+如果你的应用只需要访问一个 MySQL 数据库实例，可以如下配置：


如果你的应用

如果我们的应用

fengmk2 · 2017-01-12T07:13:59Z

docs/source/zh-cn/practice/mysql.md

+
+#### 多数据源
+
+如果你的应用需要访问多个 MySQL 数据源，可以按照如下配置：


fengmk2 · 2017-01-12T07:14:38Z

docs/source/zh-cn/practice/mysql.md

+
+由于对 MySQL 数据库的访问操作属于 web 层中的数据处理层，因此我们强烈建议将这部分代码放在 service 层中维护。
+
+下面是一个 service 中访问 MySQL数据库的例子。


MySQL 数据库的例子 少了一个空格

fengmk2 · 2017-01-12T07:15:10Z

docs/source/zh-cn/practice/mysql.md

+```js
+// app/service/user.js
+module.exports = app => {
+  class User extends app.Service {


return class User extends app.Service {}

fengmk2 · 2017-01-12T07:15:34Z

docs/source/zh-cn/practice/mysql.md

+};
+```
+
+## 如何编写 crud 语句


fengmk2 · 2017-01-12T07:18:56Z

docs/source/zh-cn/practice/mysql.md

+  otherField: 'other field value',
+  modifiedAt: this.app.mysql.literals.now, // `now()` on db server
+};
+const result = yield this.app.mysql.update('posts', row); // 更新 posts 表中的记录


等价的 SQL 语句写出来吧，像上面那样

fengmk2 · 2017-01-12T07:24:50Z

docs/source/zh-cn/practice/mysql.md

+
+## 使用 ORM
+
+// 等待补充


@mansonchor @jtyjty99999 这些都补充上吧

使用ORM 和 使用DAO 不知道要写啥，不是我加这个栏目没概念

这个等 @jtyjty99999 补吧

这个我先去掉，后面再新开文档单独写 ORM 和 DAO

@fengmk2 嗯，现在主要是配套插件还没跟上，等ok了再仔细写写这块

fengmk2 · 2017-01-12T07:25:57Z

docs/source/zh-cn/practice/mysql.md

+如果需要调用mysql内置的函数（或表达式），可以使用`Literal`。
+
+#### 内置表达式
+- NOW(): 数据库当前系统时间，通过`app.mysql.literals.now`获取。


NOW(): 数据库当前系统时间，通过app.mysql.literals.now获取。

NOW()：数据库当前系统时间，通过 app.mysql.literals.now 获取。

中英文标点不要混用，都是有中文标点符号

fengmk2 · 2017-01-12T07:26:59Z

docs/source/zh-cn/practice/mysql.md

+
+```js
+yield this.app.mysql.insert(table, {
+  create_time: this.app.mysql.literals.now


create_time: this.app.mysql.literals.now, 少了逗号

如果对象末行规范加逗号的话，我统一扫一遍加下

fengmk2 · 2017-01-12T07:27:49Z

docs/source/zh-cn/practice/mysql.md

+```
+
+#### 自定义表达式
+下例展示了如何调用mysql内置的`CONCAT(s1, ...sn)`函数，做字符串拼接。


的 CONCAT(s1, ...sn) 函

需要加上空格

mansonchor · 2017-01-12T08:27:24Z

@fengmk2 再看看

atian25 · 2017-01-12T08:43:46Z

rebase master

fengmk2

LGTM

我将 todo 的去掉合并。

atian25 requested a review from mansonchor January 11, 2017 06:33

fengmk2 added this to the v1.x milestone Jan 11, 2017

fengmk2 added the type: document label Jan 11, 2017

fengmk2 reviewed Jan 11, 2017

View reviewed changes

docs/source/zh-cn/practice/mysql.md

// 数据库名

database: 'test',

},

// ...

Copy link

Member

fengmk2 Jan 11, 2017

Choose a reason for hiding this comment

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

db2 的配置示例也加上

jtyjty99999 force-pushed the doc-mysql branch 2 times, most recently from 8f613ce to 8c4745b Compare January 11, 2017 07:50

atian25 reviewed Jan 11, 2017

View reviewed changes

docs/source/zh-cn/practice/mysql.md

之后可以通过 controller 获取 service 层拿到的数据。

```javascript

Copy link

Member

atian25 Jan 11, 2017

Choose a reason for hiding this comment

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

js

atian25 reviewed Jan 11, 2017

View reviewed changes

mansonchor reviewed Jan 11, 2017

View reviewed changes

dead-horse reviewed Jan 11, 2017

View reviewed changes

docs/source/zh-cn/practice/mysql.md

};

```

## 异步处理

Copy link

Member

dead-horse Jan 11, 2017

Choose a reason for hiding this comment

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

异步处理与 mysql 插件没有太大关系吧？

dead-horse reviewed Jan 11, 2017

View reviewed changes

jtyjty99999 force-pushed the doc-mysql branch from 8c4745b to aa53511 Compare January 12, 2017 05:51

popomore mentioned this pull request Jan 12, 2017

中文文档 #34

Closed

31 tasks

fengmk2 reviewed Jan 12, 2017

View reviewed changes

docs/source/zh-cn/practice/mysql.md

};

```

## 如何编写 crud 语句

Copy link

Member

fengmk2 Jan 12, 2017

Choose a reason for hiding this comment

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

CRUD

fengmk2 reviewed Jan 12, 2017

View reviewed changes

mansonchor force-pushed the doc-mysql branch from bd8edac to 570e295 Compare January 12, 2017 07:20

fengmk2 reviewed Jan 12, 2017

View reviewed changes

mansonchor force-pushed the doc-mysql branch 2 times, most recently from fb3d561 to a4bd002 Compare January 12, 2017 08:26

mansonchor force-pushed the doc-mysql branch from a4bd002 to 65d2ac6 Compare January 12, 2017 09:51

fengmk2 approved these changes Jan 12, 2017

View reviewed changes

fengmk2 force-pushed the doc-mysql branch from 65d2ac6 to 2446c51 Compare January 12, 2017 10:23

jtyjty99999 and others added 2 commits January 12, 2017 18:24

docs: add mysql doc

5db9ac5

docs: improve mysql doc

92c554b

fengmk2 force-pushed the doc-mysql branch from 2446c51 to 92c554b Compare January 12, 2017 10:24

fengmk2 merged commit 82d993c into master Jan 12, 2017

fengmk2 deleted the doc-mysql branch January 12, 2017 10:24


		# 访问 MySQL 实现数据库操作

		在 WEB 应用方面 MySQL 是最常见，最好的关系型数据库之一。包括阿里巴巴在内，很多网站的开发都选择 MySQL 作为网站数据库。本篇文档介绍了如何使用 egg 框架及其插件来访问数据库。


		在 WEB 应用方面 MySQL 是最常见，最好的关系型数据库之一。包括阿里巴巴在内，很多网站的开发都选择 MySQL 作为网站数据库。本篇文档介绍了如何使用 egg 框架及其插件来访问数据库。

		## egg-MySQL


		## egg-MySQL

		我们提供了 [egg-MySQL](https://github.com/eggjs/egg-mysql)插件来访问 MySQL 数据库，这个插件既可以访问普通的 MySQL 数据库，也可以访问阿里云提供的在线数据库服务 [RDS](https://www.aliyun.com/product/rds?spm=5176.8142029.388261.35.puj0DS)（ApsaraDB for RDS，简称RDS）。


		## 安装与配置

		在 package.json 里面依赖 egg-MySQL模块，并通过 `config/plugin.js` 配置启动 MySQL 插件:


		下面是一个 service 中访问 MySQL数据库的例子。

		更多 service 层的介绍，可以参考 egg 文档中的 service 一节。


		更多 service 层的介绍，可以参考 egg 文档中的 service 一节。

		```javascript


		之后可以通过 controller 获取 service 层拿到的数据。

		```javascript


		因此，对于一个事务来讲，一定伴随着 beginTransaction, commit 或 rollback ，分别代表事务的开始，成功和失败回滚。

		egg-MySQL 提供了两种类型的事务。


		## 直接执行 sql 语句

		插件本身也支持拼接与直接执行 sql 语句。使用 `query` 可以执行合法的 sql 语句。


		#### 单数据源

		如果你的应用只需要访问一个 MySQL 数据库实例，可以如下配置：


		#### 多数据源

		如果你的应用需要访问多个 MySQL 数据源，可以按照如下配置：


		由于对 MySQL 数据库的访问操作属于 web 层中的数据处理层，因此我们强烈建议将这部分代码放在 service 层中维护。

		下面是一个 service 中访问 MySQL数据库的例子。

docs: add mysql doc #234

docs: add mysql doc #234

Conversation

jtyjty99999 commented Jan 11, 2017

Checklist

Affected core subsystem(s)

Description of change

fengmk2 commented Jan 11, 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-io commented Jan 11, 2017 • edited

Current coverage is 97.54% (diff: 100%)

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

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

mansonchor commented Jan 12, 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

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

mansonchor commented Jan 12, 2017

atian25 commented Jan 12, 2017

fengmk2 left a comment

Choose a reason for hiding this comment

codecov-io commented Jan 11, 2017 •

edited