企业官网建设流程全解析

• 配置中心
• 后端
• 微服务

导读

disconf 在提供完整的浏览器控制台之外，还向开发者开放了一套基于 HTTP 的 REST 管理接口（统一以/api为前缀）。本文以仓库内 12-open-api-for-web.md 为骨架，完整梳理 app、auth、env、config、zk 五类接口的请求方式、参数与返回格式，并结合 disconf-web 模块的真实 Controller 源码（AppController.java、ConfigNewController.java、ConfigReadController.java、ConfigUpdateController.java、UserController.java、ZooController.java 等）进行印证与扩充。读者阅读后将掌握：如何用 curl 完成登录会话、如何通过 API 创建与查询 App/环境/配置、如何以文件与文本两种方式上下传配置、如何检查 ZK 部署情况，从而有能力开发自定义的 Web 控制台界面或把配置管理能力集成进自有系统。

前言：接口权限模型与统一返回结构

文档开篇即明确这一系列管理接口的目标：让开发者具有自定义定制 Web 控制台界面的能力，并强调"以下接口均需要权限控制"。仓库源码印证了这一设计：

• 管理类接口（app、env、config 的增删改查、zkdeploy）默认全部经过登录拦截。拦截器 LoginInterceptor.java 采用"Session → Redis → 拒绝"的两级会话校验：优先读 HttpSession，未命中则回查 Redis，仍无登录信息则返回login.error（错误码ErrorCode.LOGIN_ERROR）并拦截请求；同时它会自动种植名为DISCONF的 Cookie（见 LoginConstant.java 中XONE_COOKIE_NAME_STRING）。
• 会话在 Redis 中的默认过期时间为SESSION_EXPIRE_TIME = 1800秒（30 分钟）；登录时remember=1则使用SESSION_EXPIRE_TIME2 = 3600 * 24 * 30（30 天），Cookie 本身的年龄为一年（XONE_COOKIE_AGE = 60 * 60 * 24 * 365）。
• 需要免登录的接口（如/api/account/signin、/api/account/session）通过@NoAuth注解显式放行，该注解定义在 NoAuth.java，作用于方法级别。
• 所有 Controller 的类级路径统一拼接WebConstants.API_PREFIX（即/api，见 WebConstants.java），因此文档中的/api/app/list实际由@RequestMapping("/api/app")+@RequestMapping("/list")组合而成。

管理接口的返回统一封装为JsonObjectBase风格 JSON：message（校验失败时的字段级错误信息）、sessionId（每次请求生成的会话跟踪 ID）、success（"true"/"false"）、result（业务数据）以及列表场景下的page分页对象（含result、totalCount、pageNo、pageSize、order、orderBy等字段）。下面按接口类别逐一展开。

app 接口：App 的查询与创建

GET /api/app/list —— 返回所有 App 列表

• 请求类型：GET
• 参数示例：N/A（无参数）
• 返回示例：

{"message":{},"sessionId":"3e560be1-9000-4a5c-8371-35312040d8ac","success":"true","page":{"result":[ {"id":2,"name":"disconf_demo"}],"order":null,"orderBy":null,"totalCount":1,"pageNo":null,"pageSize":null ,"footResult":null}}

从 AppController.java 的实现看，该接口调用appMgr.getAuthAppVoList()获取当前登录用户有权限查看的 App 列表（而非全量），再以buildListSuccess(appListVos, appListVos.size())包装为分页结构，totalCount即列表长度。

POST /api/app —— 生成一个 App

• 请求类型：POST
• 参数：

• 返回示例：

{"message":{},"sessionId":"31617346-2020-4016-bc0d-f7a62d91945b","success":"true","result":"创建成功"}

对应源码 AppController.java：表单绑定AppNewForm后先经appValidator.validateCreate(appNewForm)做业务校验，再调用appMgr.create(appNewForm)落库，成功返回"创建成功"。emails用于把负责人邮箱与 App 关联，后续配置变更邮件通知会用到这些邮箱。

auth 接口：会话获取、登录与退出

auth 接口是整个管理 API 的入口——后续所有写操作（创建 App、新建/修改/删除配置等）都需要先通过登录建立会话，因此建议任何自定义控制台的第一步都是先调用/api/account/signin并用 Cookie 或 sessionId 维持后续请求。

GET /api/account/session —— 获取当前会话信息

• 请求类型：GET
• 参数示例：N/A
• 返回示例：

{"message":{},"sessionId":"9d466ef4-1782-451a-8a4c-e2b99601dcba","success":"true","result":{"visitor" :{"id":6,"name":"admin","role":null}}}

源码位于 UserController.java：userMgr.getCurVisitor()返回当前访问者（Visitor），未登录时返回全局错误syserror.inner。注意该接口标注了@NoAuth，说明其用途是探测当前会话状态：返回success:true即已有有效会话，可直接调用其他管理接口。

POST /api/account/signin —— 登录

• 请求类型：POST
• 参数：

• 失败示例：

{"message":{"field":{"password":"密码不正确"}},"sessionId":"29efac2d-fec1-40c7-b0d2-8433fb8a8c2c","success" :"false","status":2000}

• 成功示例：

{"message":{},"sessionId":"53e68882-bf9a-47ab-a1f6-ba347906c2a5","success":"true","result":{"visitor" :{"id":6,"name":"admin","role":null}}}

源码细节（UserController.java）：

• 表单类 SigninForm.java 中name、password均标注@NotNull/@NotEmpty，remember必须是 0 或 1（@Range(min = 0, max = 1)），否则校验直接失败。
• 校验失败时message.field携带具体字段错误（如password: 密码不正确），status为错误码 2000。
• 登录成功后expireTime按remember取值（30 分钟或 30 天），由redisLogin.login(request, user, expireTime)写入 Redis 会话，并把visitor一并返回。

GET /api/account/signout —— 退出

• 请求类型：GET
• 参数示例：N/A
• 返回示例：

{"message":{},"sessionId":"e6c3134d-ba55-4e34-837d-46d08604e2b1","success":"true","result":{"ok":"ok" }}

实现见 UserController.java：redisLogin.logout(request)清除 Redis 中的登录态，返回{"ok":"ok"}。

env 接口：环境列表

GET /api/env/list —— 返回所有环境的列表

• 请求类型：GET
• 参数示例：N/A
• 返回示例：

{"message":{},"sessionId":"826141a9-3255-4beb-88c8-018e40981f6c","success":"true","page":{"result":[ {"id":1,"name":"rd"},{"id":2,"name":"qa"},{"id":3,"name":"local"},{"id":4,"name":"online"}],"order":null ,"orderBy":null,"totalCount":4,"pageNo":null,"pageSize":null,"footResult":null}}

对应 EnvController.java：envMgr.getVoList()返回EnvListVo（id + name）。注意环境 ID 是后续创建配置（appId/envId/version）时的入参依据，环境名（如rd）则是客户端拉取配置接口（/api/config/item?env=rd）以及 ZK 结点路径（/disconf/{{app}}_{{version}}_{{env}}）的组成部分，两者需要对应。

config 接口：配置项的创建、查询、下载、修改与删除

config 管理接口是本文档最核心的部分，仓库中由三个 Controller 协同实现，前缀均为/api/web/config：

• ConfigNewController.java：新建配置项（/item）、上传文件建配置（/file）、文本建配置（/filetext）；
• ConfigReadController.java：版本列表、配置列表（含/不含 ZK 信息）、单个配置、ZK 数据、单文件/批量下载；
• ConfigUpdateController.java：修改配置项/配置文件、删除配置。

POST /api/web/config/item —— 创建配置项

• 请求类型：POST
• 参数：

• 返回示例：

{"message":{},"sessionId":"dc7b3355-2763-4122-bb69-96d2eb282027","success":"true","result":"创建成功"}

实现要点（ConfigNewController.java）：key、value由 ConfNewItemForm.java 声明为@NotNull/@NotEmpty；appId/version/envId继承自ConfNewForm。创建时以DisConfigTypeEnum.ITEM区分类型，configMgr.newConfig(...)完成落库与 ZK 结点写入。

POST /api/web/config/file —— 生成配置（上传文件方式）

• 请求类型：POST（multipart 表单，字段名myfilerar）
• 参数：

• 返回示例：

{"message":{},"sessionId":"b6a75894-a94b-4075-a4c7-05ed0be6b016","success":"true","result":"创建成功"}

源码补充了文档未写明的上传限制（ConfigNewController.java）：文件大小上限fileSize = 1024 * 1024 * 4（4MB），仅允许.properties与.xml扩展名（allowExtName），由FileUploadValidator.validateFile校验；文件以 UTF-8 读取为字符串，并以file.getOriginalFilename()作为配置 key。

POST /api/web/config/filetext —— 生成配置（上传文本方式）

• 请求类型：POST
• 参数：

• 返回示例：

{"message":{},"sessionId":"b6a75894-a94b-4075-a4c7-05ed0be6b016","success":"true","result":"创建成功"}

实现见 ConfigNewController.java：fileName、fileContent标注@NotNull，直接以文本内容建配置，适合由程序动态生成配置文件的场景（相比上传文件省去 multipart 处理）。

GET /api/web/config/versionlist —— 根据 app、env 获取所有版本列表

• 请求类型：GET
• 参数：

• 返回示例：

{"message":{},"sessionId":"cd908c6a-1dba-42b4-8a6f-3cb997ffb747","success":"true","page":{"result":["1_0_0_0" ],"order":null,"orderBy":null,"totalCount":1,"pageNo":null,"pageSize":null,"footResult":null}}

实现见 ConfigReadController.java，调用configMgr.getVersionListByAppEnv(appId, envId)。result中即为该 App+环境组合下已经存在的全部版本号（例如1_0_0_0），可据此向下钻取配置列表。

GET /api/web/config/list —— 获取配置列表（含 ZK 机器信息）

• 请求类型：GET
• 参数：

• 返回示例：

{"message":{},"sessionId":"95839567-d098-4456-b44a-dd556454ec65","success":"true","page":{"result":[ {"configId":148,"appName":"disconf_demo","appId":2,"version":"1_0_0_0","envId":1,"envName":"rd","type" :"配置文件","typeId":0,"key":"autoconfig.properties","value":"auto=bbdxxjdccdcccdxdcdc\nxx","createTime" :"20150320130619","modifyTime":"201603271140","machineSize":1,"machineList":[{"machine":"localhost_0_4b860678-290a-4bdf-9a79-2600598f419b" ,"value":"{\"auto\":\"bbdxxjdccdcccdxdcdc\",\"xx\":\"\"}","errorList":[]}],"errorNum":0}, ... ]}}

源码细节（ConfigReadController.java）：表单 ConfListForm.java 要求appId/version/envId均非空；列表默认按name升序排列（setOrderBy(Columns.NAME)+setOrder(ASC)）；configMgr.getConfigList(confListForm, true, false)的第一个布尔参数hasValue为true，表示结果携带 ZK 机器信息。返回的每一条配置都包含：

• configId：后续按 ID 查询、下载、修改、删除的关键入参；
• type/typeId：区分配置文件（typeId=0）与配置项（typeId=1）；
• machineSize、machineList、errorNum：该配置当前被多少客户端机器订阅、各机器（如localhost_0_4b860678-...）在 ZK 上的实际值快照及其错误列表、出错总数——这是监控配置下发健康度的核心数据。

GET /api/web/config/simple/list —— 获取配置列表（无 ZK 信息）

• 请求类型：GET
• 参数：与/list相同（appId、envId、version）
• 返回示例：

{"message":{},"sessionId":"ee170075-0974-4b9a-b341-f8f33beda453","success":"true","page":{"result":[ {"configId":155,"appName":"测试","appId":3,"version":"1_0_0_0","envId":1,"envName":"rd","type":"配置文件","typeId" :0,"key":"a.properties","value":"","createTime":"20160423115212","modifyTime":"201604231152","machineSize" :0,"machineList":[],"errorNum":0},{"configId":154,"appName":"测试","appId":3,"version":"1_0_0_0","envId" :1,"envName":"rd","type":"配置项","typeId":1,"key":"dd","value":"","createTime":"20160423114721","modifyTime" :"201604231147","machineSize":0,"machineList":[],"errorNum":0}],"order":"asc","orderBy":"name","totalCount" :2,"pageNo":null,"pageSize":null,"footResult":null}}

实现上（ConfigReadController.java）调用configMgr.getConfigList(confListForm, false, false)，hasValue=false即不再拉取 ZK 机器信息，machineSize/machineList为空。当自定义控制台只关心配置元数据（key、value、类型、时间）而不关心机器时，该接口更轻量。

GET /api/web/config/{configId} —— 获取单个配置内容

• 请求类型：GET
• 参数：

• 返回示例：

{"message":{},"sessionId":"2944fb48-3735-48a0-a1bf-ad1bf4980c71","success":"true","result":{"configId" :148,"appName":"disconf_demo","appId":2,"version":"1_0_0_0","envId":1,"envName":"rd","type":"配置文件","typeId" :0,"key":"autoconfig.properties","value":"auto=bbdxxjdccdcccdxdcdc\nxx","createTime":"20150320130619" ,"modifyTime":"201603271140","machineSize":0,"machineList":null,"errorNum":0}}

实现见 ConfigReadController.java：@PathVariable long configId绑定路径参数，先configValidator.valideConfigExist(configId)校验存在性，再返回ConfListVo。value字段即配置原文（配置文件为完整文件内容，配置项为键值字符串）。

GET /api/web/config/zk/{configId} —— 获取配置对应的机器列表及数据

• 请求类型：GET
• 参数：

• 返回示例：

{"message":{},"sessionId":"6bf69e7e-a6f7-4c42-b04e-0336c132fef2","success":"true","result":{"datalist" :[{"machine":"localhost_0_4b860678-290a-4bdf-9a79-2600598f419b","value":"{\"auto\":\"bbdxxjdccdcccdxdcdc \",\"xx\":\"\"}","errorList":[]}],"errorNum":0,"machineSize":1}}

实现见 ConfigReadController.java，调用configMgr.getConfVoWithZk(configId)返回MachineListVo。它把"该配置被哪些客户端订阅、各机器在 ZK 上的值快照、错误列表"一次性返回，是排障与自建监控面板的利器。

GET /api/web/config/download/{configId} —— 以文件形式下载配置

• 请求类型：GET
• 参数：

• 返回示例：N/A（响应体为文件内容而非 JSON）

实现见 ConfigReadController.java：校验存在性后取config.getValue()作为响应字节流，Content-Disposition: attachment; filename=<URLEncoder 编码后的配置名>，浏览器/客户端即可获得与原文件名一致的下载文件。

GET /api/web/config/downloadfilebatch —— 批量下载配置

• 请求类型：GET
• 参数：

• 返回示例：N/A（返回 tar 包字节流）

实现见 ConfigReadController.java：configMgr.getDisconfFileList(confListForm)收集该组合下的全部配置文件，使用 TarUtils.java 打包为 tar，文件名前缀形如APP{appId}_ENV{envId}_VERSION{version}，适合一次性备份或迁移整套环境配置。

PUT /api/web/config/item/{configId} —— 修改配置项的值

• 请求类型：PUT
• 参数：

• 返回示例：

{"message":{},"sessionId":"004cd21f-f2d4-4754-b5c1-f215266d63c4","success":"true","result":"修改成功，邮件发 送失败，请检查邮箱配置"}

实现见 ConfigUpdateController.java：configMgr.updateItemValue(configId, value)先更新数据库，随即configMgr.notifyZookeeper(configId)向 ZK 写入UPDATE-NOTIFYING通知（该常量定义于 Constants.java），客户端收到结点变更后回源拉取新值。返回的result是邮件通知的结果文案——示例中显示"邮件发送失败，请检查邮箱配置"即说明配置更新已成功但邮件通知未发出（需检查 application-demo.properties 中的邮箱相关配置）。

PUT /api/web/config/file/{configId} —— 以上传文件形式修改配置文件

• 请求类型：PUT（multipart，字段名myfilerar）
• 参数：

• 返回示例：

{"message":{},"sessionId":"6bacbb02-faf4-416b-bf12-b33d4df328ca","success":"true","result":"修改成功，邮件发 送失败，请检查邮箱配置"}

注意：文档标记请求类型为 PUT，但当前仓库源码 ConfigUpdateController.java 中该端点实际为@RequestMapping(value = "/file/{configId}", method = RequestMethod.POST)。以仓库源码为准，调用时应使用POST。校验规则与新建文件一致：4MB 上限、仅.properties/.xml；更新后同样执行notifyZookeeper(configId)触发全量下发。

PUT /api/web/config/filetext/{configId} —— 以上传文件内容形式修改配置文件

• 请求类型：PUT
• 参数：

• 返回示例：

{"message":{},"sessionId":"6bacbb02-faf4-416b-bf12-b33d4df328ca","success":"true","result":"修改成功，邮件发 送失败，请检查邮箱配置"}

实现见 ConfigUpdateController.java：@NotNull String fileContent直接作为配置新值写入并通知 ZK。

DELETE /api/web/config/{configId} —— 删除配置

• 请求类型：DELETE
• 参数：

• 返回示例：

{"message":{},"sessionId":"b2e36172-1a60-479a-acc9-5854e3f93d98","success":"true","result":"删除成功"}

实现见 ConfigUpdateController.java：configValidator.validateDelete(configId)校验后调用configMgr.delete(configId)，同步删除数据库记录与 ZK 结点。

zk 接口：ZK 部署情况

GET /api/zoo/zkdeploy —— 获取 ZK 部署情况

• 请求类型：GET
• 参数：

• 返回示例：N/A

实现见 ZooController.java：zkDeployValidator.verify(zkDeployForm)由 appId/envId 解析出 app 名与环境名，再调用zkDeployMgr.getDeployInfo(appName, envName, version)返回该组合在 ZK 上的目录树与结点部署明细，result.hostInfo即部署详情。此接口可用于自建"配置健康巡检"或"部署拓扑可视化"页面。

补充：同文件内还有两个免登录的 ZK 辅助接口——GET /api/zoo/hosts返回 ZK 地址（zooConfig.getZooHosts()）、GET /api/zoo/prefix返回 ZK 路径前缀（zooConfig.getZookeeperUrlPrefix()），客户端启动时正是通过这两个接口获取 ZK 连接信息（见 WatchFactory.java），配置值来自 zoo.properties 对应的ZooConfig属性。

与客户端 API 的分工：管理面与拉取面

本文档（面向 Web 控制台的 API）与仓库中另一份 12-open-api-for-web-client.md（面向客户端的 API）构成完整闭环，两者边界清晰：

• 管理接口（本文）：/api/web/config/*等，需要登录权限，负责配置的增删改查、版本管理、机器监控与 ZK 部署查看，供 Web 控制台或管理类系统调用；
• 客户端拉取接口：GET /api/config/item、GET /api/config/file（@NoAuth免登录），客户端用它拉取配置值/文件内容——例如 FetcherMgrImpl.java 的getValueFromServer解析ValueVo（status/message/value 三段结构），downloadFileFromServer把文件下载到本地目录；
• 更新通知面：配置更新后由 web 端在 ZK 写入通知，客户端通过订阅 ZK 结点（路径格式/disconf/{{app_name}}_{{version}}_{{env}}/item/{key}与/disconf/{{app_name}}_{{version}}_{{env}}/file/{key}，路径拼装见 ZooPathMgr.java）感知变更，再回源拉取。

因此，管理接口中"修改配置 →notifyZookeeper写通知"这一动作，正是驱动客户端热更新的关键一环。调用链可概括为：

PUT /api/web/config/item/{configId}（改库） → configMgr.notifyZookeeper(configId)（ZK 结点写入 UPDATE-NOTIFYING） → 客户端 NodeWatcher 收到变更事件（disconf-client watch 模块） → 客户端回源 GET /api/config/item 或 /api/config/file 拉取新值

实战：用 curl 走通"登录 → 查列表 → 建配置 → 改配置"全流程

基于以上接口，给出一个可直接复用的 curl 调用序列（把http://your-disconf-host替换为实际地址，并先调用/api/account/signin建立会话；管理接口的鉴权依赖DISCONFCookie，建议使用-c/-b维持 Cookie）：

# 1. 登录，记住会话 Cookie curl -c cookies.txt -X POST 'http://your-disconf-host/api/account/signin' \ -d 'name=admin' -d 'password=your_password' -d 'remember=0' # 2. 获取 App 列表，取出 appId（如 2） curl -b cookies.txt 'http://your-disconf-host/api/app/list' # 3. 获取环境列表，取出 envId（如 1=rd） curl -b cookies.txt 'http://your-disconf-host/api/env/list' # 4. 查询该 App+环境已有的版本 curl -b cookies.txt 'http://your-disconf-host/api/web/config/versionlist?appId=2&envId=1' # 5. 创建配置项（appId=2, envId=1, version=1_0_0_0） curl -b cookies.txt -X POST 'http://your-disconf-host/api/web/config/item' \ -d 'appId=2' -d 'envId=1' -d 'version=1_0_0_0' \ -d 'key=discountRate' -d 'value=0.5' # 6. 以文本方式创建配置文件（fileName + fileContent） curl -b cookies.txt -X POST 'http://your-disconf-host/api/web/config/filetext' \ -d 'appId=2' -d 'envId=1' -d 'version=1_0_0_0' \ -d 'fileName=autoconfig.properties' -d 'fileContent=auto=bbdxxjdccdcccdxdcdc' # 7. 列出配置（含 ZK 机器信息），取出 configId curl -b cookies.txt 'http://your-disconf-host/api/web/config/list?appId=2&envId=1&version=1_0_0_0' # 8. 修改配置项值（configId 替换为实际值），并触发 ZK 通知 curl -b cookies.txt -X PUT 'http://your-disconf-host/api/web/config/item/148' -d 'value=0.8' # 9. 批量下载该环境下全部配置（tar 包） curl -b cookies.txt -o conf_backup.tar \ 'http://your-disconf-host/api/web/config/downloadfilebatch?appId=2&envId=1&version=1_0_0_0'

小结

disconf 面向 Web 控制台开放的这套/api接口，覆盖了 App、会话、环境、配置（新建/查询/下载/修改/删除）与 ZK 部署查看的全部管理能力，配合@NoAuth放行的登录接口与 Cookie 会话机制，足以支撑开发者构建自定义控制台、自建运维面板或将配置管理能力嵌入既有系统。使用时请留意两点：一是写操作前必须先登录建立会话；二是文档与源码存在少量不一致（如PUT /api/web/config/file/{configId}在源码中实为 POST），应以仓库实际代码为准。相关实现细节可进一步查阅 disconf-web 模块的 Controller 与 service 层代码，以及 ConfigFetcherController.java（客户端拉取接口的实现）理解管理面与拉取面的完整协作。

• 配置中心
• 后端
• 微服务