配置中心后端微服务【免费下载链接】disconfDistributed Configuration Management Platform(分布式配置管理平台)项目地址https://gitcode.com/gh_mirrors/di/disconf点击查看免费下载导读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 分钟登录时remember1则使用SESSION_EXPIRE_TIME2 3600 * 24 * 3030 天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风格 JSONmessage校验失败时的字段级错误信息、sessionId每次请求生成的会话跟踪 ID、successtrue/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参数#namedesc是否必要1appapp 的名字是2desc描述是3emails关联的邮箱列表逗号分隔否返回示例{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.javauserMgr.getCurVisitor()返回当前访问者Visitor未登录时返回全局错误syserror.inner。注意该接口标注了NoAuth说明其用途是探测当前会话状态返回success:true即已有有效会话可直接调用其他管理接口。POST /api/account/signin —— 登录请求类型POST参数#namedesc是否必要1name用户名是2password密码是3remember是否记住自己0不记住1记住是失败示例{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/NotEmptyremember必须是 0 或 1Range(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.javaredisLogin.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.javaenvMgr.getVoList()返回EnvListVoid name。注意环境 ID 是后续创建配置appId/envId/version时的入参依据环境名如rd则是客户端拉取配置接口/api/config/item?envrd以及 ZK 结点路径/disconf/{{app}}_{{version}}_{{env}}的组成部分两者需要对应。config 接口配置项的创建、查询、下载、修改与删除config 管理接口是本文档最核心的部分仓库中由三个 Controller 协同实现前缀均为/api/web/configConfigNewController.java新建配置项/item、上传文件建配置/file、文本建配置/filetextConfigReadController.java版本列表、配置列表含/不含 ZK 信息、单个配置、ZK 数据、单文件/批量下载ConfigUpdateController.java修改配置项/配置文件、删除配置。POST /api/web/config/item —— 创建配置项请求类型POST参数#namedesc是否必要1key配置项 key是2value配置项 value是3appIdapp是4version版本是5envId环境是返回示例{message:{},sessionId:dc7b3355-2763-4122-bb69-96d2eb282027,success:true,result:创建成功}实现要点ConfigNewController.javakey、value由 ConfNewItemForm.java 声明为NotNull/NotEmptyappId/version/envId继承自ConfNewForm。创建时以DisConfigTypeEnum.ITEM区分类型configMgr.newConfig(...)完成落库与 ZK 结点写入。POST /api/web/config/file —— 生成配置上传文件方式请求类型POSTmultipart 表单字段名myfilerar参数#namedesc是否必要1myfilerar配置文件是2appIdapp是3version版本是4envId环境是返回示例{message:{},sessionId:b6a75894-a94b-4075-a4c7-05ed0be6b016,success:true,result:创建成功}源码补充了文档未写明的上传限制ConfigNewController.java文件大小上限fileSize 1024 * 1024 * 44MB仅允许.properties与.xml扩展名allowExtName由FileUploadValidator.validateFile校验文件以 UTF-8 读取为字符串并以file.getOriginalFilename()作为配置 key。POST /api/web/config/filetext —— 生成配置上传文本方式请求类型POST参数#namedesc是否必要1fileName文件名是2fileContent文件内容是3appIdapp是4version版本是5envId环境是返回示例{message:{},sessionId:b6a75894-a94b-4075-a4c7-05ed0be6b016,success:true,result:创建成功}实现见 ConfigNewController.javafileName、fileContent标注NotNull直接以文本内容建配置适合由程序动态生成配置文件的场景相比上传文件省去 multipart 处理。GET /api/web/config/versionlist —— 根据 app、env 获取所有版本列表请求类型GET参数#namedesc是否必要1appIdapp是2envId环境否返回示例{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参数#namedesc是否必要1appIdapp是2envId环境是3version版本是返回示例{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:autobbdxxjdccdcccdxdcdc\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区分配置文件typeId0与配置项typeId1machineSize、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)hasValuefalse即不再拉取 ZK 机器信息machineSize/machineList为空。当自定义控制台只关心配置元数据key、value、类型、时间而不关心机器时该接口更轻量。GET /api/web/config/{configId} —— 获取单个配置内容请求类型GET参数#namedesc是否必要1configIdconfigId是返回示例{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:autobbdxxjdccdcccdxdcdc\nxx,createTime:20150320130619 ,modifyTime:201603271140,machineSize:0,machineList:null,errorNum:0}}实现见 ConfigReadController.javaPathVariable long configId绑定路径参数先configValidator.valideConfigExist(configId)校验存在性再返回ConfListVo。value字段即配置原文配置文件为完整文件内容配置项为键值字符串。GET /api/web/config/zk/{configId} —— 获取配置对应的机器列表及数据请求类型GET参数#namedesc是否必要1configIdconfigId是返回示例{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参数#namedesc是否必要1configIdconfigId是返回示例N/A响应体为文件内容而非 JSON实现见 ConfigReadController.java校验存在性后取config.getValue()作为响应字节流Content-Disposition: attachment; filenameURLEncoder 编码后的配置名浏览器/客户端即可获得与原文件名一致的下载文件。GET /api/web/config/downloadfilebatch —— 批量下载配置请求类型GET参数#namedesc是否必要1appIdapp是2envId环境是3version版本是返回示例N/A返回 tar 包字节流实现见 ConfigReadController.javaconfigMgr.getDisconfFileList(confListForm)收集该组合下的全部配置文件使用 TarUtils.java 打包为 tar文件名前缀形如APP{appId}_ENV{envId}_VERSION{version}适合一次性备份或迁移整套环境配置。PUT /api/web/config/item/{configId} —— 修改配置项的值请求类型PUT参数#namedesc是否必要1configIdconfigId是2valuevalue是返回示例{message:{},sessionId:004cd21f-f2d4-4754-b5c1-f215266d63c4,success:true,result:修改成功邮件发 送失败请检查邮箱配置}实现见 ConfigUpdateController.javaconfigMgr.updateItemValue(configId, value)先更新数据库随即configMgr.notifyZookeeper(configId)向 ZK 写入UPDATE-NOTIFYING通知该常量定义于 Constants.java客户端收到结点变更后回源拉取新值。返回的result是邮件通知的结果文案——示例中显示邮件发送失败请检查邮箱配置即说明配置更新已成功但邮件通知未发出需检查 application-demo.properties 中的邮箱相关配置。PUT /api/web/config/file/{configId} —— 以上传文件形式修改配置文件请求类型PUTmultipart字段名myfilerar参数#namedesc是否必要1configIdconfigId是2myfilerar文件是返回示例{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参数#namedesc是否必要1configIdconfigId是2fileContent文件内容是返回示例{message:{},sessionId:6bacbb02-faf4-416b-bf12-b33d4df328ca,success:true,result:修改成功邮件发 送失败请检查邮箱配置}实现见 ConfigUpdateController.javaNotNull String fileContent直接作为配置新值写入并通知 ZK。DELETE /api/web/config/{configId} —— 删除配置请求类型DELETE参数#namedesc是否必要1configIdconfigId是返回示例{message:{},sessionId:b2e36172-1a60-479a-acc9-5854e3f93d98,success:true,result:删除成功}实现见 ConfigUpdateController.javaconfigValidator.validateDelete(configId)校验后调用configMgr.delete(configId)同步删除数据库记录与 ZK 结点。zk 接口ZK 部署情况GET /api/zoo/zkdeploy —— 获取 ZK 部署情况请求类型GET参数#namedesc是否必要1appIdapp是2envId环境是3version版本是返回示例N/A实现见 ZooController.javazkDeployValidator.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/fileNoAuth免登录客户端用它拉取配置值/文件内容——例如 FetcherMgrImpl.java 的getValueFromServer解析ValueVostatus/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 nameadmin -d passwordyour_password -d remember0 # 2. 获取 App 列表取出 appId如 2 curl -b cookies.txt http://your-disconf-host/api/app/list # 3. 获取环境列表取出 envId如 1rd 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?appId2envId1 # 5. 创建配置项appId2, envId1, version1_0_0_0 curl -b cookies.txt -X POST http://your-disconf-host/api/web/config/item \ -d appId2 -d envId1 -d version1_0_0_0 \ -d keydiscountRate -d value0.5 # 6. 以文本方式创建配置文件fileName fileContent curl -b cookies.txt -X POST http://your-disconf-host/api/web/config/filetext \ -d appId2 -d envId1 -d version1_0_0_0 \ -d fileNameautoconfig.properties -d fileContentautobbdxxjdccdcccdxdcdc # 7. 列出配置含 ZK 机器信息取出 configId curl -b cookies.txt http://your-disconf-host/api/web/config/list?appId2envId1version1_0_0_0 # 8. 修改配置项值configId 替换为实际值并触发 ZK 通知 curl -b cookies.txt -X PUT http://your-disconf-host/api/web/config/item/148 -d value0.8 # 9. 批量下载该环境下全部配置tar 包 curl -b cookies.txt -o conf_backup.tar \ http://your-disconf-host/api/web/config/downloadfilebatch?appId2envId1version1_0_0_0小结disconf 面向 Web 控制台开放的这套/api接口覆盖了 App、会话、环境、配置新建/查询/下载/修改/删除与 ZK 部署查看的全部管理能力配合NoAuth放行的登录接口与 Cookie 会话机制足以支撑开发者构建自定义控制台、自建运维面板或将配置管理能力嵌入既有系统。使用时请留意两点一是写操作前必须先登录建立会话二是文档与源码存在少量不一致如PUT /api/web/config/file/{configId}在源码中实为 POST应以仓库实际代码为准。相关实现细节可进一步查阅 disconf-web 模块的 Controller 与 service 层代码以及 ConfigFetcherController.java客户端拉取接口的实现理解管理面与拉取面的完整协作。赞分享配置中心后端微服务【免费下载链接】disconfDistributed Configuration Management Platform(分布式配置管理平台)项目地址https://gitcode.com/gh_mirrors/di/disconf点击查看免费下载相关推荐disconf-web 开放 HTTP API 完全指南用接口自定义你的配置管理控制台disconf web 开放 HTTP API 完全指南用接口自定义你的配置管理控制台 本文以 docs/source/tutorial web/src/12配置中心后端微服务disconf-web 分布式配置管理平台 Web 控制台安装部署实战指南disconf web 分布式配置管理平台 Web 控制台安装部署实战指南 本指南以 DisconfDistributed Configuration Man配置中心后端微服务构建自定义配置管理工具Apollo开放平台API终极指南构建自定义配置管理工具Apollo开放平台API终极指南 Apollo是一个分布式配置管理平台可以方便地实现配置的统一管理和发布。通过Apollo开放平台A配置中心后端微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考