hiApi(final Envelop envelop) {
final String name = Ux.getString(envelop);
final String email = Ux.getString1(envelop);
return Ux.future(new JsonObject().put("name", name).put("email", email));
}
```
您同样可以得到响应：
```json
{
"data": {
"name": "lang.yu-async",
"email": "silentbalanceyh@126.com"
}
}
```
#### 3.1.2. Ux中取参
目前您已经看到了很多类似`Ux.getJson，Ux.getString` 的工具方法，由于这些方法是为interface模式量身定制，主要目的就是从Envelop中读取各种各样的数据，所以此处对`Ux`中的`get`系方法进行一个简单的说明：
1. get系的方法有两种读数据的模式：
1. 直接读取索引为`0, 1, 2`位置的数据。
2. 传入索引读取，可读取索引值超过2的数据。
2. 支持的返回值类型包括：
1. io.vertx.core.json.JsonArray
2. io.vertx.core.json.JsonObject
3. java.lang.Integer
4. java.lang.Long
5. java.lang.String
6. 自定义的Java类型（内部执行Jackson序列化）
不提供完备类型的目的是此处做了弱化类型处理，即使类型不严格，您也可以在Worker内部直接转换，而根据Vert.x中Json为王的模式，最频繁使用的一个类型实际是`JsonObject`。
汇总后的API统计表格如：
> 表格中所有的方法可直接使用`Ux.method`的方式直接调用。
| 类型 | 索引0,1,2 | 传入索引 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| JsonArray | getArray(Envelop)
getArray1(Envelop)
getArray2(Envelop)
| getArray(Envelop, int) |
| JsonObject | getJson(Envelop)
getJson1(Envelop)
getJson2(Envelop)
| getJson(Envelop, int) |
| Integer | getInteger(Envelop)
getInteger1(Envelop)
getInteger2(Envelop)
| getInteger(Envelop, int) |
| Long | getLong(Envelop)
getLong1(Envelop)
getLong2(Envelop)
| getLong(Envelop, int) |
| String | getString(Envelop)
getString1(Envelop)
getString2(Envelop)
| getString(Envelop, int) |
| T | getT(Envelop, Class\)
getT1(Envelop, Class\)
getT2(Envelop, Class\)
| getT(Envelop, int, `Class`) |
除开上述的API以外，还有两个特殊的API：
* `Ux.getBody(Envelop)`：等价于`envelop.body()`。
* `Ux.getBodyT(Envelop)`：直接根据JsonObject数据转换成T结构。
#### 3.1.3. 探索式
一旦使用了Envelop就要求您对Zero中的Envelop核心数据结构有一定的了解，Zero的设计是希望更自由，所以不会仅仅满足于上边提到的**标准模式**，更有意思的是**探索模式** ，还是先看一段代码：
**Agent代码段**
```java
@GET
@Path("/async-seek")
@Address("ZERO://WORKER/ASYNC/SEEK")
String hiSeek(@QueryParam("name") final String name,
@QueryParam("email") final String email);
```
**Worker代码段**
```java
@Address("ZERO://WORKER/ASYNC/SEEK")
public Future hiSeek(final String name, final String email) {
return Ux.future(new JsonObject().put("name", name).put("email", email));
}
```
上述代码依旧不会出错，**注意**的是这里的匹配并不是使用的形参名称匹配，而是**顺序**，所以这种模式遵循两个原则：
1. Agent组件方法和Worker组件方法名称可以不相同（二者联系依赖@Address）。
2. Agent组件方法和Worker组件方法的参数列表顺序必须一致，匹配时会按照顺序进行匹配。
如果把Worker中的方法定义成：
```java
public Future hiSeek(final String email, final String name) ...
```
最终会变成Agent的name会传给email形参，而Agent的email会传给name形参。
#### 3.1.4. 关于JSR303
> 这部分内容在`> 0.6.0`的版本中生效，`0.6.0`的版本中不支持。
最后提供一个例子，结合前边提到的验证部分看看如何在interface中使用JSR303的验证注解。
**Agent代码段**
```java
@GET
@Path("/jsr303-api")
@Address("ZERO://WORKER/JSR303/API")
String hiApi(
@NotNull(message = "{field.notnull}")
@QueryParam("name") final String name,
@Null(message = "{field.null}")
@QueryParam("email") final String email);
```
**Worker代码段**
```java
@Address("ZERO://WORKER/JSR303/API")
public Future hiSeek(final String name, final String email) {
return Ux.future(new JsonObject().put("name", name).put("email", email));
}
```
**vertx-validation.properties内容**
```properties
field.null=对不起参数`name`必须是null！
field.notnull=对不起参数`name`是必须参数！
```
如此配置后，您就可以收到下边响应信息：
```json
{
"code": -60000,
"message": "[ERR-60000] (Validator) Web Exception occurs: (400) ...",
"info": "对不起参数`name`必须是null！"
}
```
### 3.2. 扩展参数
**扩展参数**是Zero对Worker组件的进一步扩展，它可以让您在Worker组件中十分容易读取**环境参数**，这些参数按类型进行区分。
#### 3.2.1. 代码示例
**Agent代码**
```java
@GET
@Path("/extension-api")
@Address("ZERO://WORKER/EXTENSION/API")
String hiExtension(
@QueryParam("name") final String name,
@QueryParam("email") final String email);
```
**Worker代码**
```java
@Address("ZERO://WORKER/EXTENSION/API")
public Future hiExtension(final String name,
final HttpServerRequest request,
final String email) {
System.out.println(request);
return Ux.future(new JsonObject().put("name", name).put("email", email));
}
```
执行该Worker时候可以从后端看到输出：
```shell
io.vertx.ext.web.impl.HttpServerRequestWrapper@41715ad1
```
#### 3.2.2. 上下文对象
如此，Worker组件就拿到了相关上下文对象，和Agent不同的是Worker组件支持的上下文对象相对少一些：
| 对象类型 | 备注信息 |
| ------------------------------------: | ----------------: |
| io.vertx.up.commune.config.XHeader | 多应用、多语言、多租户环境专用对象 |
| io.vertx.ext.web.Session | HTTP会话对象 |
| io.vertx.core.http.HttpServerRequest | HTTP请求对象 |
| io.vertx.core.http.HttpServerResponse | HTTP响应对象 |
| io.vertx.core.Vertx | Vertx实例 |
| io.vertx.core.eventbus.EventBus | EventBus实例 |
| io.vertx.ext.auth.User | User登录用户对象 |
在Worker自由态的情况下，基础参数的顺序和Agent参数顺序保持一致，上下文对象按类型进行匹配以及跳过，而上下文对象可以定义在方法签名的参数表中任意位置处，此处Zero使用了简单的\*\* 压缩排序**算法。不过通常的写法是让用户将上下文对象追加到参数列表尾部，如示例中的**推荐写法\*\*：
```java
public Future hiExtension(final String name, final String email,
final HttpServerRequest request)
```
再者，上下文对象的引入会导致开发人员对整个环境执行数据流的破坏性操作，所以在某些场景下，要求您了解了Zero执行流程后再调用相关的数据流方法（典型方法如HttpServerResponse中的输出）；一般引入上下文对象的核心目的是\*\* 读取环境数据\*\*，希望您牢记这一点。
### 3.3. 容错
最后一个章节讲讲**容错**，其实有了Zero中的基础异常结构，容错代码的开发变得相对简单，本章用两个例子来讲解容错流程的开发。
#### 3.3.1. 同步容错
**Agent代码段**
```java
@GET
@Path("/error-sync")
@Address("ZERO://WORKER/ERROR/SYNC")
String hiSync(
@QueryParam("name") final String name,
@QueryParam("email") final String email);
```
**Worker代码段**
```java
@Address("ZERO://WORKER/ERROR/SYNC")
public Envelop hiSync(final String name,
final String email) {
final WebException error =
new _500InternalServerException(this.getClass(), "Sync Error");
return Envelop.failure(error);
}
```
发送请求会收到异常响应：
```json
{
"code": -60007,
"message": "[ERR-60007] (ErrorActor) Web Exception occurs: (500) ..."
}
```
> 同步模式下如果要生成异常响应，必须使用类似Envelop的对象作为返回值，因为它包含了双态（失败和成功）信息。
#### 3.3.2. 异步容错
**Agent代码段**
```java
@GET
@Path("/error-async")
@Address("ZERO://WORKER/ERROR/ASYNC")
String hiAsync(
@QueryParam("name") final String name,
@QueryParam("email") final String email);
```
**Worker代码段**
```java
@Address("ZERO://WORKER/ERROR/ASYNC")
public Future hiAsync(final String name,
final String email) {
final WebException error =
new _500InternalServerException(this.getClass(), "Async Error");
return Future.failedFuture(error);
}
```
发送请求会收到异常响应：
```json
{
"code": -60007,
"message": "[ERR-60007] (ErrorActor) Web Exception occurs: (500) ..."
}
```
#### 3.3.3. 关于throw
Worker组件中如果出现了异常信息，最少应该执行下边的代码结构操作：
```java
try{
// 主代码
}catch(XXXException ex){
// 异常代码
}
```
而在异常代码区域执行两种对象的构造：
1. 使用`Envelop.failure`构造Envelop对象（同步）。
2. 使用`Future.failedFuture`构造Future对象（异步）。
在Worker组件编程过程中，不建议直接throw一个异常，如果此处throw了异常，会中断Zero的请求执行流程导致本次请求失败，也证明您的代码部分有没有考虑到的部分，而函数本身还具有副作用，是一个偏函数。 那么catch中一般做什么呢？推荐如下：
1. 使用日志记录器记录下来重要的异常日志。
2. 调用printStackTrace()方法打印调试信息到控制台。
3. 「最终」构造Envelop或Future的**双态**对象（用双态是因为都包含了成功和失败，实际就是一个常见的单子Monad对象。）
> 如果您的代码中出现了异常被抛出，最终会在客户端收到如下异常响应信息：
```json
{
"code": -60002,
"message": "[ERR-60002] (AsyncAim) Web Exception occurs: (500) - ..."
}
```
## 「肆」小结
本文详细探索了Worker组件的各种开发模式以及编程风格，Worker组件在Zero框架中属于核心业务逻辑代码，您的整个程序逻辑大部分都是在此处完成，于是学习Worker的写法尤其重要。本章包含内容如下：
1. 在Zero中如何启用EventBus实现异步数据流。
2. Zero中支持的三种开发模式（也可以理解为编程风格）：
1. 同步模式。
2. 异步模式（Feture模式）。
3. 回调模式（Handler模式）。
3. 扩展后的Worker组件方法签名以及业务逻辑层容错流程。