用Dart 搭建图书 REST Framework— 第一部分

微服务的时代，如何快速方便地交换数据变得至关重要。


Jermaine Oppong 在他的文章 Building RESTful Web APIs with Dart, Aqueduct and PostgreSQL 给了一个很完整的案例，在这里和大家一起分享。

1.设置和运行示例

pub global activate aqueduct
aqueduct create fave_reads && cd fave_reads

在项目fave_reads的文件结构中， 我们重点需要关注：

bin/
  main.dart
lib/
  fave_reads_sink.dart
pubspec.yaml
  • bin/main.dart 创建我们的服务器并启动应用程序
  • lib/fave_reads_sink.dart 用来设置配置
  • pubspec.yaml 包文件。 类似于Node.js开发的package.json

使用下面的命令启动应用程序：

aqueduct serve # 或 `dart bin/main.dart`

我们现在有一个运行在http://localhost:8081的服务器，其中/example是唯一创建的路由。 访问http://localhost:8081/example将返回如下响应：

{ "key": "value" }

值得一提的是，Aqueduct 使用 RequestSink的概念，处理应用程序的初始化，包括设置路由，授权和数据库连接。
应用程序需要一个RequestSink子类来处理接收请求。 本例中有一个FaveReadsSink扩展了RequestSink的基类，使我们可以重载它的方法。 如：setupRouter和willOpen 。 setupRouter允许我们用关联的controllers 和其他middleware来定义我们的路由，而willOpen允许我们在路由设置之后和应用程序可以接收请求之前执行任何异步初始化。
下面我们通过在setupRouter方法中创建第二条路由：

router.route('/').listen((request) async {
  return new Response.ok('Hello world')
    ..contentType = ContentType.TEXT;
});

使用方法级联，我们可以将contentType属性设置为text/plain。 ContentType实用程序内置Dart，可以通过以下样式使用(支持HTML, JSON and TEXT）：

new ContentType(primaryType, subType, {String charset, Map parameters});

重新启动服务器。 访问根路径应该得到：


helloworld.png

Dart 应用程序实例可以扩展cpu的内核数。例如： 在bin/main.dart中，当调用app.start时，它当前的内核数设置为2：

await app.start(numberOfInstances: 2);

为了启用这个功能，我们需要将从“dart:io”库导入Dart的Platform类，并修改main.dart，如下所示：

import 'dart:io' show Platform;
Future main() async {
  ...
  ...
  await app.start(numberOfInstances: Platform.numberOfProcessors);
  ...
}

2. 使用CRUD操作实现路由

2.1 路由Router

在Router 对象上调用route方法时注册路由来定义请求路径。 当我们的FaveReadsSink子类中的setupRouter方法被调用时，就会发生注册。
setupRouter方法提供了一个Router对象作为参数，然后我们使用它来定义我们的每个路由：

// lib/fave_reads_sink.dart
@override
void setupRouter(Router router) {
  router.route(’/path-1’).listen(...);
  router.route(’/path-2’).listen(...);
  router.route(’/path-3’).listen(...); // and so on
}

调用route方法接收一个包含路径名的字符串，接着是一个监听方法，用来处理业务逻辑。 路由可以包含路径变量，它是占位符标记，表示路径中的任何参数：

router.route('/items/:itemID');

上面的例子声明了一个路径变量itemID，它匹配“/items/0”，“/items/1”，“/items/foo”等等。 itemID的值分别为“0”，“1”和“foo”。
路径变量也可以是可选的，所以我们可以像这样设置它们：

router.route('/items/[:itemID]);

基于此，我们修改lib/fave_reads_sink.dart文件中的setupRouter实现方法，如下所示：

@override
void setupRouter((Router router) async {
  router.route('/books[/:index]').listen((Request incomingRequest) async {
    return new Response.ok('Showing all books.');
  });
  router.route('/').listen((Request incomingRequest) async {
    return new Response.ok('<h1>Welcome to FaveReads</h1>')
      ..contentType = ContentType.HTML;
  });
});

根路径目前返回HTML内容。 我们还定义了一个“/books”路由，它接受一个名为index的可选路径变量。 这将是我们用来实现CRUD操作的地方。
调用路由方法会返回一个RouteController，它的listen方法，我们用来定义要运行的业务逻辑。还有其他两种方法，即pipe和generate。 后者允许我们创建一个新的HTTPController对象，以更好地处理我们的请求。
listen方法接受一个包含表示传入请求的Request对象的闭包。 然后，我们可以从中获取我们需要的信息，执行转换并返回响应。
我们进一步修改文件使我们的每个操作返回不同的响应：

router.route('/books[/:index]').listen((Request incomingRequest) async {
  String reqMethod = incomingRequest.innerRequest.method;
  String index = incomingRequest.path.variables["index"];
  
  if (reqMethod == 'GET') {
    if(index != null) {
      return new Response.ok('Showing book by index: $index');
    }
    return new Response.ok('Showing all books.');
  } else if (reqMethod == 'POST') {
    return new Response.ok('Added a book.');
  } else if (reqMethod == 'PUT') {
    return new Response.ok('Added a book.');
  } else if (reqMethod == 'DELETE') {
    return new Response.ok('Added a book.');
  }
  // If all else fails
  return new Response(405, null, 'Not sure what you\'re asking here');
});

2.2 HTTPController

HTTPControllers通过映射到对应的“处理程序方法”来响应HTTP请求。 只要路径匹配，Router就会向HTTPController发送请求。
我们将创建一个扩展HTTPController的BooksController，新建文件controller/ books_controller.dart 并有以下内容：

import '../fave_reads.dart';

class BooksController extends HTTPController {
  // invoked for GET /books
  @httpGet // HTTPMethod meta data
  Future<Response> getAllBooks() async => new Response.ok('Showing all books');
  
  // invoked for GET /books/:index
  @httpGet // HTTPMethod meta data
  Future<Response> getBook(@HTTPPath("index") int idx) async => new Response.ok('Showing single book');
  
  // invoked for POST /books
  @httpPost // HTTPMethod meta data
  Future<Response> addBook() async => new Response.ok('Added a book');
  
  // invoked for PUT /books
  @httpPut // HTTPMethod meta data
  Future<Response> updateBook() async => new Response.ok('Updated a book');
  
  // invoked for DELETE /books
  @httpDelete  // HTTPMethod meta data
  Future<Response> deleteBook() async => new Response.ok('Deleted a book');
}

解释一下：

  1. BooksController子类由5个处理程序方法组成，称为响应方法。
  2. 每个响应方法都使用反映适当请求方法的常量进行注释：@httpGet，@httpPost，@httpPut，@httpDelete。 其他方法将使用HTTPMethod，如@HTTPMethod('PATCH')。
  3. 每个响应方法都会返回一个类型为Response的Future。 Dart中的Future就等同于JavaScript的Promises 。
  4. 响应方法可以将请求中的值绑定到它的参数。 我们用getBook() 响应方法参数来看这个：@HTTPPath("index") int idx。 其路径变量被转换为一个整数并被分配给一个名为idx的变量。

如果没有响应方法匹配请求方法（例如PATCH），则返回405方法不允许响应。 修改lib/fave_reads_sink.dart文件并使用这个控制器：

import 'fave_reads.dart';
import 'controller/books_controller.dart';
...
...
@override
void setupRouter((Router router) async {
  router
    .route(‘/books/[:index]’)
    .generate(() => new BooksController()); // replaces `listen` method
...

在终端运行 aqueduct serve 或 dart bin/main.dart 重启服务器.

我们可以用 Postman. 来做测试：

book.png

2.3 测试数据源 Mocking our datasource

我们在controller/books_controller.dart中创建一个测试数据的数组：

import '../fave_reads.dart';

List books = [
  {
    'title': 'Head First Design Patterns',
    'author': 'Eric Freeman',
    'year': 2004
  },
  {
    'title': 'Clean Code: A handbook of Agile Software Craftsmanship',
    'author': 'Robert C. Martin',
    'year': 2008
  },
  {
    'title': 'Code Complete: A Practical Handbook of Software Construction',
    'author': 'Steve McConnell',
    'year': 2004
  },
];

class BooksController extends HTTPController {...}

然后更新BooksController中的响应方法来操作此数据集：

class BooksController extends HTTPController {
  @httpGet
  Future<Response> getAll() async => new Response.ok(books);

  @httpGet
  Future<Response> getSingle(@HTTPPath("index") int idx) async {
    if (idx < 0 || idx > books.length - 1) { // index out of range
      return new Response.notFound(body: 'Book does not exist');
    }
    return new Response.ok(books[idx]);
  }

  @httpPost
  Future<Response> addSingle() async {
    var book = request.body.asMap(); // `request` represents the current request. This is a property inside HTTPController base class
    books.add(book);
    return new Response.ok(book);
  }

  @httpPut
  Future<Response> replaceSingle(@HTTPPath("index") int idx) async {
    if (idx < 0 || idx > books.length - 1) { // index out of range
      return new Response.notFound(body: 'Book does not exist');
    }
    var body = request.body.asMap();
    for (var i = 0; i < books.length; i++) {
      if (i == idx) {
        books[i]["title"] = body["title"];
        books[i]["author"] = body["author"];
        books[i]["year"] = body["year"];
      }
    }
    return new Response.ok(body);
  }

  @httpDelete
  Future<Response> delete(@HTTPPath("index") int idx) async {
    if (idx < 0 || idx > books.length - 1) { // index out of range
      return new Response.notFound(body: 'Book does not exist');
    }
    books.removeAt(idx);
    return new Response.ok('Book successfully deleted.');
  }
}

2.4 重构解决方案

我们通过@HTTPBody() metadata 重构POST操作

@httpPost
Future<Response> addSingle(@HTTPBody() Map book) async {
  books.add(book);
  return new Response.ok('Added new book.');
}

这里，尝试将请求有效载荷解析为Map类型。 只要自定义类型扩展了HTTPSerializable类型，我们也可以指定自定义类型，而不仅仅使用内置类型。 让我们通过在 lib/model/book.dar中引入Book模型来实现这一点：

import '../fave_reads.dart';

class Book extends HTTPSerializable {
  String title;
  String author;
  int year;

  Book({this.title, this.author, this.year});

  @override
  Map<String, dynamic> asMap() => {
    "title": title,
    "author": author,
    "year": year,
  };

  @override
  void readFromMap(Map requestBody) {
    title = requestBody["title"];
    author = requestBody["author"];
    year = requestBody["year"];
  }
}

总结如下：

  1. 我们的Book模型实现了HTTPSerializable，它是一个用于从HTTP请求中解析信息的实用工具。
  2. 定义asMap和readFromMap(Map requestBody) 方法。 asMap将在JSON响应被发送回客户端时使用，而readFromMap将检索请求主体并提取数据以填充模型的属性。
    现在我们只需要使用这个模型：
// lib/controller/book_controller.dart
import '../fave_reads.dart';
import 'model/book.dart';

List books = [
  new Book(
    title: 'Head First Design Patterns',
    author: 'Eric Freeman',
    year: 2004
  ),
  new Book(
    title: 'Clean Code: A handbook of Agile Software Craftsmanship', 
    author: 'Robert C. Martin', 
    year: 2008
  ),
  new Book(
    title: 'Code Complete: A Practical Handbook of Software Construction',
    author: 'Steve McConnell',
    year: 2004
  ),
];

class BooksController extends HTTPController {
  // ...
  // ...
  Future<Response> addSingle(@HTTPbody() Book book) async { // note the `Book` type being used
    books.add(book);
    return new Response.ok(book);
  }
  //...
  //...
}

以上部分的源代码，请参看： available on github

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 203,456评论 5赞 477
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 85,370评论 2赞 381
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 150,337评论 0赞 337
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,583评论 1赞 273
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,596评论 5赞 365
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,572评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,936评论 3赞 395
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,595评论 0赞 258
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,850评论 1赞 297
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,601评论 2赞 321
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,685评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,371评论 4赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,951评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,934评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,167评论 1赞 259
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 43,636评论 2赞 349
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,411评论 2赞 342

推荐阅读更多精彩内容

  • Spring Cloud
    Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具（例如配置管理，服务发现，断路器，智...
    卡卡罗2017阅读 134,585评论 18赞 139
  • Spring Framework 5 MVC 官方手册译文
    Spring Web MVC Spring Web MVC 是包含在 Spring 框架中的 Web 框架，建立于...
    Hsinwong阅读 22,300评论 1赞 92
  • iOS 面试宝典 没有比这更全的了（持续更新）
    1.ios高性能编程 (1).内层 最小的内层平均值和峰值(2).耗电量 高效的算法和数据结构(3).初始化时...
    欧辰_OSR阅读 29,294评论 8赞 265
  • 阿曼达20160823《恶意》
    “我就是恨你，我恨你抢先实现了我的理想，我恨你优越的生活，我恨当初如此不屑的你如今有了光明的前途，我恨我自己还没来...
    活着1111阅读 154评论 0赞 0
  • 西湖畔
    杭州悄悄来， 西湖在心怀， 远远的看， 静静的观， 少许游人在湖畔。 夜晚静静临， 晚饭在眼前， 淡淡的尝， 慢慢...
    橘子洲的鱼阅读 195评论 0赞 2