附录 3 ActFramework 内置服务

ActFramework 提供了一些内置服务, 方便应用开发和使用. 所有的系统内置服务均被映射到以 /~/ 开头的 URL 路径上.

1. 内置服务参考

1.1 GET /~/apibook

ActFramework 在开发模式下扫描程序源代码生成 API 文档. 访问 API 文档的坐标是 GET /~/apibook:

image

1.2 GET /~/asset

ActFramework 内置了一些 css/js 资源文件, 主要用来支持:

  1. 开发模式下的错误页面
  2. 开发模式下的 API 文档.

一般情况下应用程序不应该访问 /~/asset/ 下面的资源

1.3 POST /~/i18n/locale

该端点为应用程序提供改变当前用户会话的 Locale 的服务. 具体信息请参考国际化

1.4 POST /~/i18n/locale

该端点为应用程序提供改变当前用户会话时区的服务. 具体信息请参考国际化

1.5 GET /~/info

提供当前应用的信息.

当通过浏览器直接访问该端点, 获得类似下面的信息:

  1. _           _            _    _        _  
  2.  |_|  |_  |   |   / \  \    /  / \  |_)  |   | \ 
  3.  | |  |_  |_  |_  \_/   \/\/   \_/  | \  |_  |_/ 
  5.               powered by ActFramework r1.8.7-2f28
  7.  version: v1.0-SNAPSHOT-180408_1425
  8. scan pkg: com.mycom.helloworld
  9. base dir: /tmp/1/helloworld
  10.      pid: 31898
  11.  profile: dev
  12.     mode: DEV
  14.      zen: Explicit is better than implicit.

如果是 JavaScript 发出 JSON 类型的请求, 则获得类似下面的返回结果:

  1. {
  2.     "actVersion": "r1.8.7-2f28", 
  3.     "appName": "helloworld", 
  4.     "appVersion": "v1.0-SNAPSHOT-180408_1425", 
  5.     "baseDir": "/tmp/1/helloworld/.", 
  6.     "group": "", 
  7.     "mode": "DEV", 
  8.     "pid": "31898", 
  9.     "profile": "dev"
  10. }

1.6 GET /~/job/{id}/progress

这是一个 websocket 服务端点, 为应用提供查询异步作业进度服务. 具体信息参考作业调度

1.7 GET /~/pid

返回应用的进程号, 直接从浏览器访问结果示例:

  1. 31898

发出 Accept=application/json 的请求,返回结果为:

  1. {
  2.     "pid": "31898"
  3. }

1.8 GET /~/version

返回当前应用的版本信息. 访问该段口得到的返回结果示例:

  1. {
  2.     "act": {
  3.         "artifactId": "act", 
  4.         "buildNumber": "2f28", 
  5.         "packageName": "act", 
  6.         "projectVersion": "1.8.7", 
  7.         "unknown": false, 
  8.         "version": "r1.8.7-2f28"
  9.     }, 
  10.     "app": {
  11.         "artifactId": "helloworld", 
  12.         "buildNumber": "180408_1425", 
  13.         "packageName": "com.mycom.helloworld", 
  14.         "projectVersion": "1.0-SNAPSHOT", 
  15.         "unknown": false, 
  16.         "version": "v1.0-SNAPSHOT-180408_1425"
  17.     }
  18. }

这个结果和 HTTP Request 的 Accept 头设置没有关系.

1.9 GET /~/zen

返回应用的箴言列表. 这个服务端点对应用没有具体意义

2. 安全考虑与禁用内置服务

在 ActFramework 内置的服务端点中有些会泄露系统内部信息, 应该加以安全控制. 如果应用使用 act-aaa 提供安全服务, 除下列服务外所有其他的内置服务端点都需要接受安全认证:

  • GET /~/apibook
  • GET /~/asset
  • POST /~/i18n/locale
  • POST /~/i18n/timezone
  • GET /~/zen

明确地讲, 访问下面的内置服务需要接受认证:

  • GET /~/info
  • GET /~/job/{id}/progress
  • GET /~/pid
  • GET /~/version

如果需要完全禁用内置服务, 在应用配置文件中加上:

  1. built_in_req_handler=false

注意 下面的服务端点可能会影响应用的功能, 因此不能被禁用:

  • GET /~/asset
  • POST /~/i18n/locale
  • POST /~/i18n/timezone
  • GET /~/job/{id}/progress

apibook 只能用于开发模式, 因此也不会被禁用.