docs: add RESTful documents #247

dead-horse · 2017-01-12T16:29:10Z

No description provided.

fengmk2 · 2017-01-12T18:13:51Z

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

+title: 实现 RESTful API
+---
+
+通过 web 技术开发服务给客户端提供接口，可能是各个 web 框架最广泛的应用之一。这篇文章我们拿 [cnode](https://cnodejs.org/) 社区的接口来看一看通过 egg 如何实现 RESTful API 给客户端调用。


[RESTful](https://zh.wikipedia.org/wiki/REST) 加上 wiki 链接

fengmk2 · 2017-01-12T18:31:00Z

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

+- 响应状态码：204
+- 响应体：空
+
+### 错误


错误处理

fengmk2 · 2017-01-12T18:32:19Z

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

+
+## 实现
+
+在约定好接口之后，我们可以开始动手基于 egg 来实现了。


我们可以开始动手基于 egg 来实现了。

我们可以开始动手实现了。

fengmk2 · 2017-01-12T18:32:59Z

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

+
+### 初始化项目
+
+还是通过[快速入门](../intro/quickstart.md)章节介绍的 egg-init 工具来初始化我们的应用


https://github.com/eggjs/egg-init 加上链接

fengmk2 · 2017-01-12T18:42:12Z

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

+
+### 注册路由
+
+首先，我们先按照前面的设计来注册[路由](../core/router.md)，egg 提供了一个便捷的方式来创建 RESTful 风格的路由，并将一个资源的接口映射到对应的 controller 文件。在 `app/router.js` 中：


egg 提供

框架提交

atian25 · 2017-01-12T22:22:08Z

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

+还是通过[快速入门](../intro/quickstart.md)章节介绍的 egg-init 工具来初始化我们的应用
+
+```bash
+$ egg-init cnode-api --type=empty


改为 simple 吧，参见 #218

这里我就是想要初始化一个空项目，现在的 empty 里面的内容都太多了，改完刚刚好。

atian25 · 2017-01-12T22:23:56Z

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

+
+### controller 开发
+
+在 [controller](../core/controller.md) 中，我们只需要实现 `app.resources` 约定的 [RESTful 风格的 URL 定义](../basics/router.md#restful-风格的-url-定义) 中我们需要提供的接口即可。例如我们来实现创建一个 Topic 的接口：


那个 hash 能链上么？

https://eggjs.org/zh-cn/basics/router#restful-风格的-url-定义

atian25 · 2017-01-12T22:24:51Z

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

+
+通过 `app.resources` 方法，我们将 Topic 这个资源的增删改查接口映射到了 `app/controller/topic.js` 文件。
+
+### controller 开发


先 controller 再 router？

那样比较尴尬，controller -> router -> service。

其实在写的时候也一般是先 router 的

atian25 · 2017-01-12T22:28:21Z

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

+
+## 测试
+
+编写完成代码后，还要记得对我们的代码编写[单元测试](../core/unittest.md)哦！具体的代码实现和测试都在 [eggjs/examples](https://github.com/eggjs/examples/tree/master/cnode-api) 中可以找到。


把cnode-api加上

fengmk2 · 2017-01-13T02:03:22Z

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

+        this.ctx.throw(result.status, errorMsg);
+      }
+      if (!result.data.success) {
+        this.logger.error('remote format error:', result.data);


这个日志不需要大量吧，onerror 不是会打么？

onerror 打印的是 throw 出去的那个 message，这里记录格式错误的 data，不过应该可以放到 throw 里面的一个属性，我看看

fengmk2 · 2017-01-13T02:08:03Z

单元测试也加上说明，真实展示 httpclient 的 mock

popomore · 2017-01-13T02:37:25Z

直接在这里把 practice 目录改了？

popomore · 2017-01-13T02:36:27Z

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

@@ -0,0 +1,258 @@
+title: 实现 RESTful API


就叫 RESTful API？

popomore · 2017-01-13T02:39:20Z

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

+- 响应状态码：200
+- 响应体：
+
+```json


popomore · 2017-01-13T02:42:38Z

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

+
+```js
+module.exports = app => {
+  app.resources('Topic', '/api/v2/topics', 'topics');


都大写？

哪里都大写？

fengmk2

LGTM

dead-horse · 2017-01-13T05:09:44Z

测试部分也加上了， practice 目录改成啥？

fengmk2 · 2017-01-13T05:16:26Z

practice 目录等 @popomore 一次性改好了。

LGTM

* 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) ...

docs: add RESTful documents

8022847

dead-horse added the type: document label Jan 12, 2017

dead-horse added this to the 1.0.0 milestone Jan 12, 2017

dead-horse requested review from fengmk2, popomore and shaoshuai0102 January 12, 2017 16:29

f

afd5d7f

fengmk2 reviewed Jan 12, 2017

View reviewed changes

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

- 响应状态码：204

- 响应体：空

### 错误

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.

错误处理

fengmk2 reviewed Jan 12, 2017

View reviewed changes

atian25 reviewed Jan 12, 2017

View reviewed changes

fengmk2 reviewed Jan 13, 2017

View reviewed changes

docs: update rest

4beefca

popomore reviewed Jan 13, 2017

View reviewed changes

popomore mentioned this pull request Jan 13, 2017

中文文档 #34

Closed

31 tasks

fengmk2 approved these changes Jan 13, 2017

View reviewed changes

docs: add service test

50a10b5

fengmk2 merged commit e6311ef into master Jan 13, 2017

fengmk2 deleted the docs-rest branch January 13, 2017 05:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add RESTful documents #247

docs: add RESTful documents #247

dead-horse commented Jan 12, 2017

fengmk2 Jan 12, 2017

fengmk2 Jan 12, 2017

fengmk2 Jan 12, 2017

fengmk2 Jan 12, 2017

fengmk2 Jan 12, 2017

atian25 Jan 12, 2017

dead-horse Jan 13, 2017

atian25 Jan 12, 2017

dead-horse Jan 13, 2017

atian25 Jan 12, 2017

dead-horse Jan 13, 2017

atian25 Jan 12, 2017

fengmk2 Jan 13, 2017

dead-horse Jan 13, 2017

fengmk2 commented Jan 13, 2017

popomore commented Jan 13, 2017

popomore Jan 13, 2017

popomore Jan 13, 2017

popomore Jan 13, 2017

dead-horse Jan 13, 2017

fengmk2 left a comment

dead-horse commented Jan 13, 2017

fengmk2 commented Jan 13, 2017


		## 实现

		在约定好接口之后，我们可以开始动手基于 egg 来实现了。


		### 初始化项目

		还是通过[快速入门](../intro/quickstart.md)章节介绍的 egg-init 工具来初始化我们的应用


		### 注册路由

		首先，我们先按照前面的设计来注册[路由](../core/router.md)，egg 提供了一个便捷的方式来创建 RESTful 风格的路由，并将一个资源的接口映射到对应的 controller 文件。在 `app/router.js` 中：


		### controller 开发

		在 [controller](../core/controller.md) 中，我们只需要实现 `app.resources` 约定的 [RESTful 风格的 URL 定义](../basics/router.md#restful-风格的-url-定义) 中我们需要提供的接口即可。例如我们来实现创建一个 Topic 的接口：


		通过 `app.resources` 方法，我们将 Topic 这个资源的增删改查接口映射到了 `app/controller/topic.js` 文件。

		### controller 开发


		## 测试

		编写完成代码后，还要记得对我们的代码编写[单元测试](../core/unittest.md)哦！具体的代码实现和测试都在 [eggjs/examples](https://github.com/eggjs/examples/tree/master/cnode-api) 中可以找到。

docs: add RESTful documents #247

docs: add RESTful documents #247

Conversation

dead-horse 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

fengmk2 commented Jan 13, 2017

popomore commented Jan 13, 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

fengmk2 left a comment

Choose a reason for hiding this comment

dead-horse commented Jan 13, 2017

fengmk2 commented Jan 13, 2017