Vert.x-Web

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web</artifactId>
  <version>5.1.10</version>
</dependency>

dependencies {
  compile 'io.vertx:vertx-web:5.1.10'
}

HttpServer server = vertx.createHttpServer();

server.requestHandler(request -> {

  // 每当有新 HTTP 请求到达服务器时，该 Handler 就会被触发执行
  HttpServerResponse response = request.response();
  response.putHeader("content-type", "text/plain");

  // 写入响应体数据并结束该 HTTP 事务
  response.end("Hello World!");
});

server.listen(8080);

HttpServer server = vertx.createHttpServer();

Router router = Router.router(vertx);

router.route().handler(ctx -> {

  // 该处理器将拦截处理进入服务器的每一个请求
  HttpServerResponse response = ctx.response();
  response.putHeader("content-type", "text/plain");

  // 写入响应并结束响应流程
  response.end("Hello World from Vert.x-Web!");
});

server.requestHandler(router).listen(8080);

router.route("/secured/*").handler(ctx -> {
  // 客户端发送的原始路径（可能包含类似 ".." 的回溯符）
  String raw = ctx.request().path();

  // 路由器内部用于路由匹配的规范化路径
  String normalized = ctx.normalizedPath();

  // 对于涉及安全鉴权或权限校验的逻辑，强烈推荐使用规范化路径
  if ("/secured/data".equals(normalized)) {
    // ...
  }
});

Route route = router.route("/some/path/");
route.handler(ctx -> {

  HttpServerResponse response = ctx.response();
  // 启用分块传输编码（Chunked），因为后续 Handler 会陆续追加输出内容。
  // 这一步只需在首个输出内容的 Handler 中设置一次。
  response.setChunked(true);

  response.write("route1\n");

  // 延时 5 秒后唤醒下一个匹配路由继续处理
  ctx.vertx().setTimer(5000, tid -> ctx.next());
});

route.handler(ctx -> {

  HttpServerResponse response = ctx.response();
  response.write("route2\n");

  // 再次延时 5 秒后唤醒下一个匹配路由
  ctx.vertx().setTimer(5000, tid -> ctx.next());
});

route.handler(ctx -> {

  HttpServerResponse response = ctx.response();
  response.write("route3");

  // 此时结束响应
  ctx.response().end();
});

router
  .get("/some/path")
  // 该处理器会自动将返回值序列化为 JSON，并自动设置 Content-Type 为 "application/json"
  .respond(
    ctx -> Future.succeededFuture(new JsonObject().put("hello", "world")));

router
  .get("/some/path")
  // 该处理器支持将任意普通 Java POJO 对象序列化为 JSON 响应
  .respond(
    ctx -> Future.succeededFuture(new Pojo()));

router
  .get("/some/path")
  .respond(
    ctx -> ctx
      .response()
      .putHeader("Content-Type", "text/plain")
      .end("hello world!"));

router
  .get("/some/path")
  // 在这种情况下，该处理器负责确保连接正常流式写入并终止
  .respond(
    ctx -> ctx
      .response()
      .setChunked(true)
      .write("写入一些文本数据..."));

router.route().blockingHandler(ctx -> {

  // 同步执行耗时较长的阻塞方法
  service.doSomethingThatBlocks();

  // 执行完毕后调用 next 流转到下一个 Handler
  ctx.next();

});

router.post("/some/endpoint").handler(ctx -> {
  ctx.request().setExpectMultipart(true);
  ctx.next();
}).blockingHandler(ctx -> {
  // ... 在 Worker 线程中执行具体的阻塞业务
});

Route route = router.route().path("/some/path/");

route.handler(ctx -> {
  // 该处理器将被以下请求路径触发：
  // `/some/path/`
  // `/some/path//`
  //
  // 但不会匹配：
  // `/some/path`（末尾显式指定斜杠时规则为严格匹配）
  // `/some/path/subdir`
});

// 不以斜杠结尾的路径属于非严格模式，末尾的斜杠可选，两者均可匹配：
Route route2 = router.route().path("/some/path");

route2.handler(ctx -> {
  // 该处理器将被以下请求路径触发：
  // `/some/path`
  // `/some/path/`
  // `/some/path//`
  //
  // 但不会匹配：
  // `/some/path/subdir`
});

Route route = router.route().path("/some/path/*");

route.handler(ctx -> {
  // 该处理器会匹配所有以 `/some/path/` 开头的请求，例如：
  // `/some/path/`
  // `/some/path/subdir`
  // `/some/path/subdir/blah.html`
  //
  // 但 **不会** 匹配：
  // `/some/path`（通配符前的末尾斜杠不可省略，以保证子路由与组合模式不会出现意外误配）
  // `/some/patha`
  // `/some/patha/`
  // 等等...
});

Route route = router.route("/some/path/*");

route.handler(ctx -> {
  // 匹配效果与上例完全相同
});

router
  .route(HttpMethod.POST, "/catalogue/products/:productType/:productID/")
  .handler(ctx -> {

    String productType = ctx.pathParam("productType");
    String productID = ctx.pathParam("productID");

    // 基于捕获的参数执行业务操作...
  });

-Dio.vertx.web.route.param.extended-pattern=true

router
  .route(HttpMethod.GET, "/flights/:from-:to")
  .handler(ctx -> {
    // 处理发往 /flights/AMS-SFO 的请求时将分别捕获：
    String from = ctx.pathParam("from"); // AMS
    String to = ctx.pathParam("to");     // SFO
    // 请注意：如果未开启前文提到的 extended 扩展参数模式，
    // "-" 会被视作变量名的一部分而非分隔符。
  });

Route route = router.route().pathRegex(".*foo");

route.handler(ctx -> {

  // 该处理器将被以下请求命中：
  // /some/path/foo
  // /foo
  // /foo/bar/wibble/foo
  // /bar/foo

  // 但不会匹配：
  // /bar/wibble
});

Route route = router.routeWithRegex(".*foo");

route.handler(ctx -> {
  // 效果与上例相同
});

Route route = router.routeWithRegex(".*foo");

// 该正则表达式匹配形如 "/foo/bar" 的路径，其中 "foo" 会被捕获为 param0，
// 而 "bar" 则会被捕获为 param1
route.pathRegex("\\/([^\\/]+)\\/([^\\/]+)").handler(ctx -> {

  String productType = ctx.pathParam("param0");
  String productID = ctx.pathParam("param1");

  // 执行业务逻辑...
});

router
  .routeWithRegex("\\/(?<productType>[^\\/]+)\\/([^\\/]+)")
  .handler(ctx -> {

    String productType = ctx.pathParam("productType");
    String productID = ctx.pathParam("param1");

    // 执行业务逻辑...
  });

Route route = router.route().method(HttpMethod.POST);

route.handler(ctx -> {
  // 该处理器仅响应 POST 请求
});

Route route = router.route(HttpMethod.POST, "/some/path/");

route.handler(ctx -> {
  // 仅响应发往以 /some/path/ 开头的 POST 请求
});

router.get().handler(ctx -> {
  // 匹配所有 GET 请求
});

router.get("/some/path/").handler(ctx -> {
  // 匹配所有发往以 /some/path/ 开头的 GET 请求
});

router.getWithRegex(".*foo").handler(ctx -> {
  // 匹配所有路径以 foo 结尾的 GET 请求
});

Route route = router.route().method(HttpMethod.POST).method(HttpMethod.PUT);

route.handler(ctx -> {
  // 同时响应 POST 或 PUT 请求
});

Route route = router.route()
  .method(HttpMethod.valueOf("MKCOL"))
  .handler(ctx -> {
    // 拦截处理 MKCOL 请求
  });

router
  .route("/some/path/")
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.setChunked(true);

    response.write("route1\n");

    // 调用下一个匹配的路由
    ctx.next();
  });

router
  .route("/some/path/")
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.write("route2\n");

    // 调用下一个匹配的路由
    ctx.next();
  });

router
  .route("/some/path/")
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.write("route3");

    // 终止响应
    ctx.response().end();
  });

route1
route2
route3

router
  .route("/some/path/")
  .order(1)
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.write("route1\n");

    ctx.next();
  });

router
  .route("/some/path/")
  .order(0)
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.setChunked(true);

    response.write("route2\n");

    ctx.next();
  });

router
  .route("/some/path/")
  .order(2)
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.write("route3");

    ctx.response().end();
  });

route2
route1
route3

router.route()
  .consumes("text/html")
  .handler(ctx -> {
    // 仅响应 Content-Type 为 `text/html` 的请求
  });

router.route()
  .consumes("text/html")
  .consumes("text/plain")
  .handler(ctx -> {
    // 响应 Content-Type 为 `text/html` 或 `text/plain` 的请求
  });

router.route()
  .consumes("text/*")
  .handler(ctx -> {
    // 响应顶级类型为 text 的所有请求（如 text/html 或 text/plain 均可匹配）
  });

router.route()
  .consumes("*/json")
  .handler(ctx -> {
    // 响应子类型为 json 的所有请求（如 text/json 或 application/json 均可匹配）
  });

router.route()
  .produces("application/json")
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();
    response.putHeader("content-type", "application/json");
    response.end(someJSON);
  });

router.route()
  .produces("application/json")
  .produces("text/html")
  .handler(ctx -> {

    HttpServerResponse response = ctx.response();

    // 获取经过内容协商后双方达成一致的最佳 MIME 类型
    String acceptableContentType = ctx.getAcceptableContentType();

    response.putHeader("content-type", acceptableContentType);
    response.end(whatever);
  });

router.route().virtualHost("*.vertx.io").handler(ctx -> {
  // 仅当请求域名满足 *.vertx.io 时执行处理
});

router.route(HttpMethod.PUT, "myapi/orders")
  .consumes("application/json")
  .produces("application/json")
  .handler(ctx -> {

    // 仅当请求为 PUT 方法、路径以 "myapi/orders" 开头、
    // Content-Type 为 "application/json" 且 Accept 头兼容 "application/json" 时触发

  });

router.allowForward(AllowForwardHeaders.FORWARD);

// 允许解析转发头，且在此模式下仅解析 "X-Forward" 系列请求头
router.allowForward(AllowForwardHeaders.X_FORWARD);

// 同时解析 RFC 标准的 "Forward" 头与非标准的 "X-Forward" 头；
// 若两者同时存在并产生冲突，以标准的 "Forward" 值为准，忽略 "X-Forward"
router.allowForward(AllowForwardHeaders.ALL);

router.allowForward(AllowForwardHeaders.NONE);

router.get("/some/path").handler(ctx -> {

  ctx.put("foo", "bar");
  ctx.next();

});

router.get("/some/path/other").handler(ctx -> {

  String bar = ctx.get("foo");
  // 基于传递的 bar 变量继续处理
  ctx.response().end();

});

router
  .route("/metadata/route")
  .putMetadata("metadata-key", "123")
  .handler(ctx -> {
    Route route = ctx.currentRoute();
    String value = route.getMetadata("metadata-key"); // 123
    // 以 123 作为响应体结束当前请求
    ctx.end(value);
  });

ctx
  .attachment("weekly-report.pdf")
  .end(pdfBuffer);

ctx.redirect("https://securesite.com/");

// 特殊快捷目标 "back"：自动将用户重定向回 Referrer 来源页面；若无来源则默认返回 "/"
ctx.redirect("back");

ctx.json(new JsonObject().put("hello", "vert.x"));
// 同样支持 JsonArray 数组
ctx.json(new JsonArray().add("vertx").add("web"));
// 也可以传入任意 Java 对象，系统会根据运行时的 JSON 编码器自动完成序列化输出
ctx.json(someObject);

ctx.is("html"); // => true
ctx.is("text/html"); // => true

// 当 Content-Type 为 application/json 时
ctx.is("application/json"); // => true
ctx.is("html"); // => false

ctx.lastModified("Wed, 13 Jul 2011 18:30:00 GMT");
// 利用该值校验客户端请求的新鲜度
if (ctx.isFresh()) {
  // 客户端本地缓存依然有效，我们可以直接短路返回 304 Not Modified
}

ctx.etag("W/123456789");

// 设置最后修改时间
ctx.lastModified("Wed, 13 Jul 2011 18:30:00 GMT");

// 快速结束响应
ctx.end();
ctx.end("body");
ctx.end(buffer);

router.get("/some/path").handler(ctx -> {

  ctx.put("foo", "bar");
  ctx.next();

});

router
  .get("/some/path/B")
  .handler(ctx -> ctx.response().end());

router
  .get("/some/path")
  .handler(ctx -> ctx.reroute("/some/path/B"));

router.get("/my-pretty-notfound-handler").handler(ctx -> ctx.response()
  .setStatusCode(404)
  .end("NOT FOUND fancy html here!!!"));

router.get().failureHandler(ctx -> {
  if (ctx.statusCode() == 404) {
    ctx.reroute("/my-pretty-notfound-handler");
  } else {
    ctx.next();
  }
});

router.get("/final-target").handler(ctx -> {
  // 从此处继续执行业务...
});

// （将请求连带查询字符串一起重路由到 /final-target）
router.get().handler(ctx -> ctx.reroute("/final-target?variable=value"));

// 更优雅安全的方式是将参数存入 RoutingContext
router.get().handler(ctx -> ctx
  .put("variable", "value")
  .reroute("/final-target"));

Router restAPI = Router.router(vertx);

restAPI.get("/products/:productID").handler(ctx -> {

  // TODO 查询指定商品信息并返回....
  ctx.response().write(productJSON);

});

restAPI.put("/products/:productID").handler(ctx -> {

  // TODO 新增或修改商品...
  ctx.response().end();

});

restAPI.delete("/products/:productID").handler(ctx -> {

  // TODO 删除商品...
  ctx.response().end();

});

Router mainRouter = Router.router(vertx);

// 处理静态资源文件
mainRouter.route("/static/*").handler(myStaticHandler);

mainRouter.route(".*\\.templ").handler(myTemplateHandler);

mainRouter.route("/productsAPI/*")
  .subRouter(restAPI);

Route route = router.get("/localized").handler(ctx -> {
  // 通过遍历与条件分支，在以用户母语回复时，
  // 能够严格遵循用户在 Accept-Language 中声明的偏好顺序。
  for (LanguageHeader language : ctx.acceptableLanguages()) {
    switch (language.tag()) {
      case "en":
        ctx.response().end("Hello!");
        return;
      case "zh":
      case "zh-CN":
        ctx.response().end("你好！");
        return;
      case "fr":
        ctx.response().end("Bonjour!");
        return;
      case "pt":
        ctx.response().end("Olá!");
        return;
      case "es":
        ctx.response().end("Hola!");
        return;
    }
  }
  // 未匹配到受支持的语言，给出兜底提示：
  ctx.response().end("抱歉，我们暂时不支持您的语言: " + ctx.preferredLanguage());
});

Route route = router.get("/somepath/*");

route.failureHandler(ctx -> {

  // 仅当路由发往以 '/somepath/' 开头的 GET 请求发生失败时被触发调用

});

Route route1 = router.get("/somepath/path1/");

route1.handler(ctx -> {

  // 模拟抛出运行时异常
  throw new RuntimeException("发生未知异常！");

});

Route route2 = router.get("/somepath/path2");

route2.handler(ctx -> {

  // 显式使请求失败，并指定状态码 403 Forbidden
  ctx.fail(403);

});

// 定义统一失败处理器
// 上述任意处理器发生失败时均会被此处的 failureHandler 拦截
Route route3 = router.get("/somepath/*");

route3.failureHandler(failureRoutingContext -> {

  int statusCode = failureRoutingContext.statusCode();

  // 若由 RuntimeException 触发则 statusCode 为 500；
  // 若由 ctx.fail(403) 触发则为 403
  HttpServerResponse response = failureRoutingContext.response();
  response.setStatusCode(statusCode).end("抱歉，当前请求无法被处理");

});

router.route().handler(BodyHandler.create());

router.route().handler(ctx -> sessionHandler.flush(ctx)
  .onSuccess(v -> ctx.end("保存成功！"))
  .onFailure(err -> {
    // 会话落盘失败...
    // 降级执行应对预案
  }));

router.route()
  .handler(SessionHandler.create(store).setCookieless(true));

router.route()
  .handler(SecurityAuditLoggerHandler.create());

router.route("/static/*").handler(StaticHandler.create());

router.route()
  .handler(
    CorsHandler.create()
      .addOriginWithRegex("vertx\\.io")
      .allowedMethod(HttpMethod.GET));

router.route().handler(ctx -> {

  // 具体的业务处理器

});

router.route().handler(MultiTenantHandler.create("X-Tenant"));

MultiTenantHandler.create("X-Tenant")
  .addTenantHandler("tenant-A", ctx -> {
    // 针对租户 A 的业务逻辑...
  })
  .addTenantHandler("tenant-B", ctx -> {
    // 针对租户 B 的业务逻辑...
  })
  // 可选：兜底默认处理器
  .addDefaultHandler(ctx -> {
    // 当未匹配到任何受支持租户时的处理...
  });

OAuth2Auth gitHubAuthProvider = GithubAuth
  .create(vertx, "CLIENT_ID", "CLIENT_SECRET");

// 为 GitHub 认证在运行中的服务上创建 OAuth2 处理器，
// 第二个参数为回调全路径
OAuth2AuthHandler githubOAuth2 = OAuth2AuthHandler.create(
  vertx,
  gitHubAuthProvider,
  "https://myserver.com/github-callback");

// 注册接收 GitHub 认证回调的端点
githubOAuth2.setupCallback(router.route("/github-callback"));

// 创建针对 Google 的 OAuth2 Provider
OAuth2Auth googleAuthProvider = OAuth2Auth.create(vertx, new OAuth2Options()
  .setClientId("CLIENT_ID")
  .setClientSecret("CLIENT_SECRET")
  .setSite("https://accounts.google.com")
  .setTokenPath("https://www.googleapis.com/oauth2/v3/token")
  .setAuthorizationPath("/o/oauth2/auth"));

// 为 Google 创建 OAuth2 处理器
OAuth2AuthHandler googleOAuth2 = OAuth2AuthHandler.create(
  vertx,
  googleAuthProvider,
  "https://myserver.com/google-callback");

// 注册接收 Google 回调的端点
googleOAuth2.setupCallback(router.route("/google-callback"));

// 根据租户分发到不同的安全认证中心
router.route().handler(
  MultiTenantHandler.create("X-Tenant")
    // 使用 GitHub 租户的用户走此通道：
    .addTenantHandler("github", githubOAuth2)
    // 使用 Google 租户的用户走此通道：
    .addTenantHandler("google", googleOAuth2)
    // 其他未授权租户直接响应 401
    .addDefaultHandler(ctx -> ctx.fail(401)));

router.route().handler(ctx -> {
  // 默认 Key 为 MultiTenantHandler.TENANT 中定义的 "tenant"，
  // 该键名可在工厂方法创建时自由指定
  String tenant = ctx.get(MultiTenantHandler.TENANT);

  switch (tenant) {
    case "google":
      // 为 Google 租户加载专属资源
      break;
    case "github":
      // 为 GitHub 租户加载专属资源
      break;
  }
});

TemplateEngine engine = HandlebarsTemplateEngine.create();
TemplateHandler handler = TemplateHandler.create(engine);

// 将所有以 /dynamic/ 开头的 GET 请求分发至模板处理器
// 例如 /dynamic/graph.hbs 会在 /templates/graph.hbs 中查找并渲染模板
router.get("/dynamic/*").handler(handler);

// 或者匹配所有以 .hbs 结尾的资源请求
router.getWithRegex(".+\\.hbs").handler(handler);