Apollo 源码解析 —— Portal 灰度全量发布
1. 概述
老艿艿：本系列假定胖友已经阅读过 《Apollo 官方 wiki 文档》 ，特别是 《Apollo 官方 wiki 文档 —— 灰度发布使用指南》。
本文接 《Apollo 源码解析 —— Portal 灰度发布》 ，分享灰度全量发布。
我们先来看看官方文档对灰度全量发布的使用指南，来理解下它的定义和流程。
如果灰度的配置测试下来比较理想，符合预期，那么就可以操作【全量发布】。
全量发布的效果是：
- 灰度版本的配置会合并回主版本，在这个例子中，就是主版本的 timeout 会被更新成 3000
- 主版本的配置会自动进行一次发布
- 在全量发布页面，可以选择是否保留当前灰度版本，默认为不保留。
我选择了不保留灰度版本，所以发布完的效果就是主版本的配置更新、灰度版本删除。点击主版本的实例列表，可以看到10.32.21.22和10.32.21.19都使用了主版本最新的配置。
灰度全量发布，和 《Apollo 源码解析 —— Portal 发布配置》 ，差异点在于，多了一步配置合并，所以代码实现上，有很多相似度。整体系统流程如下：
2. Portal 侧
2.1 NamespaceBranchController
在 apollo-portal 项目中，com.ctrip.framework.apollo.portal.controller.NamespaceBranchController ，提供 Namespace 分支的 API 。
#merge(...) 方法，灰度全量发布，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。代码如下：
1: @PreAuthorize(value = "@permissionValidator.hasReleaseNamespacePermission(#appId, #namespaceName)")
2: @RequestMapping(value = "/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/merge", method = RequestMethod.POST)
3: public ReleaseDTO merge(@PathVariable String appId, @PathVariable String env,
4: @PathVariable String clusterName, @PathVariable String namespaceName,
5: @PathVariable String branchName, @RequestParam(value = "deleteBranch", defaultValue = "true") boolean deleteBranch,
6: @RequestBody NamespaceReleaseModel model) {
7: // 若是紧急发布，但是当前环境未允许该操作，抛出 BadRequestException 异常
8: if (model.isEmergencyPublish() && !portalConfig.isEmergencyPublishAllowed(Env.fromString(env))) {
9: throw new BadRequestException(String.format("Env: %s is not supported emergency publish now", env));
10: }
11: // 合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release
12: ReleaseDTO createdRelease = namespaceBranchService.merge(appId, Env.valueOf(env), clusterName, namespaceName, branchName,
13: model.getReleaseTitle(), model.getReleaseComment(),
14: model.isEmergencyPublish(), deleteBranch);
15:
16: // 创建 ConfigPublishEvent 对象
17: ConfigPublishEvent event = ConfigPublishEvent.instance();
18: event.withAppId(appId)
19: .withCluster(clusterName)
20: .withNamespace(namespaceName)
21: .withReleaseId(createdRelease.getId())
22: .setMergeEvent(true)
23: .setEnv(Env.valueOf(env));
24: // 发布 ConfigPublishEvent 事件
25: publisher.publishEvent(event);
26: return createdRelease;
27: }- POST
/apps/{appId}/envs/{env}/clusters/{clusterName}/namespaces/{namespaceName}/branches/{branchName}/merge接口，Request Body 传递 JSON 对象。 @PreAuthorize(...)注解，调用PermissionValidator#hasReleaseNamespacePermissio(appId, namespaceName)方法，校验是否有发布配置的权限。后续文章，详细分享。- 第 7 至 10 行：校验若是紧急发布，但是当前环境未允许该操作，抛出 BadRequestException 异常。
- 第 11 至 14 行：调用
NamespaceBranchService#merge(...)方法，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。 - 第 16 至 25 行：创建 ConfigPublishEvent 对象，并调用
ApplicationEventPublisher#publishEvent(event)方法，发布 ConfigPublishEvent 事件。这部分，我们在后续文章分享。 - 第 26 行：返回 ReleaseDTO 对象。
2.2 NamespaceBranchService
在 apollo-portal 项目中，com.ctrip.framework.apollo.portal.service.NamespaceBranchService ，提供 Namespace 分支的 Service 逻辑。
#merge(...) 方法，调用 Admin Service API ，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。代码如下：
1: @Autowired
2: private AdminServiceAPI.NamespaceBranchAPI namespaceBranchAPI;
3: @Autowired
4: private ReleaseService releaseService;
5:
6: public ReleaseDTO merge(String appId, Env env, String clusterName, String namespaceName,
7: String branchName, String title, String comment,
8: boolean isEmergencyPublish, boolean deleteBranch) {
9: // 计算变化的 Item 集合
10: ItemChangeSets changeSets = calculateBranchChangeSet(appId, env, clusterName, namespaceName, branchName);
11: // 合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release
12: ReleaseDTO mergedResult = releaseService.updateAndPublish(appId, env, clusterName, namespaceName, title, comment,
13: branchName, isEmergencyPublish, deleteBranch, changeSets);
14: // 【TODO 6001】Tracer 日志
15: Tracer.logEvent(TracerEventType.MERGE_GRAY_RELEASE, String.format("%s+%s+%s+%s", appId, env, clusterName, namespaceName));
16: return mergedResult;
17: }- 第 10 行：调用
#calculateBranchChangeSet(appId, env, clusterName, namespaceName, branchName)方法，计算变化的 Item 集合。详细解析，见 「2.2.1 calculateBranchChangeSet」 。 -
第12 至 13 行：调用
ReleaseService#updateAndPublish(...)方法，调用 Admin Service API ，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。代码如下：
@Autowired
private AdminServiceAPI.ReleaseAPI releaseAPI;
public ReleaseDTO updateAndPublish(String appId, Env env, String clusterName, String namespaceName,
String releaseTitle, String releaseComment, String branchName,
boolean isEmergencyPublish, boolean deleteBranch, ItemChangeSets changeSets) {
return releaseAPI.updateAndPublish(appId, env, clusterName, namespaceName, releaseTitle, releaseComment, branchName,
isEmergencyPublish, deleteBranch, changeSets);
}-
- 方法内部，调用
ReleaseAPI#updateAndPublish(...)方法，调用 Admin Service API ，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。 可能会有胖友会问，为什么不 NamespaceBranchService 直接调用 ReleaseAPI 呢？ReleaseAPI 属于 ReleaseService 模块，对外透明、屏蔽该细节。这样，未来 ReleaseService 想要改实现，可能不是调用 ReleaseAPI 的方法，而是别的方法，也是非常方便的。
- 方法内部，调用
-
第 15 行：【TODO 6001】Tracer 日志
2.2.1 calculateBranchChangeSet
1: @Autowired
2: private ItemsComparator itemsComparator;
3: @Autowired
4: private UserInfoHolder userInfoHolder;
5: @Autowired
6: private NamespaceService namespaceService;
7: @Autowired
8: private ItemService itemService;
9:
10: private ItemChangeSets calculateBranchChangeSet(String appId, Env env, String clusterName, String namespaceName, String branchName) {
11: // 获得父 NamespaceBO 对象
12: NamespaceBO parentNamespace = namespaceService.loadNamespaceBO(appId, env, clusterName, namespaceName);
13: // 若父 Namespace 不存在，抛出 BadRequestException 异常。
14: if (parentNamespace == null) {
15: throw new BadRequestException("base namespace not existed");
16: }
17: // 若父 Namespace 有配置项的变更，不允许合并。因为，可能存在冲突。
18: if (parentNamespace.getItemModifiedCnt() > 0) {
19: throw new BadRequestException("Merge operation failed. Because master has modified items");
20: }
21: // 获得父 Namespace 的 Item 数组
22: List masterItems = itemService.findItems(appId, env, clusterName, namespaceName);
23: // 获得子 Namespace 的 Item 数组
24: List branchItems = itemService.findItems(appId, env, branchName, namespaceName);
25: // 计算变化的 Item 集合
26: ItemChangeSets changeSets = itemsComparator.compareIgnoreBlankAndCommentItem(parentNamespace.getBaseInfo().getId(), masterItems, branchItems);
27: // 设置 `ItemChangeSets.deleteItem` 为空。因为子 Namespace 从父 Namespace 继承配置，但是实际自己没有那些配置项，所以如果不清空，会导致这些配置项被删除。
28: changeSets.setDeleteItems(Collections.emptyList());
29: // 设置 `ItemChangeSets.dataChangeLastModifiedBy` 为当前管理员
30: changeSets.setDataChangeLastModifiedBy(userInfoHolder.getUser().getUserId());
31: return changeSets;
32: } - 第 11 至 20 行，父 Namespace 相关
- 第 12 行：调用
namespaceService#loadNamespaceBO(appId, env, clusterName, namespaceName)方法，获得父 NamespaceBO 对象。该对象，包含了 Namespace 的详细数据，包括 Namespace 的基本信息、配置集合。详细解析，点击方法链接查看，笔者已经添加详细注释。方法比较冗长，胖友耐心阅读，其目的是为了【第 17 至 20 行】的判断，是否有未发布的配置变更。 - 第 13 至 16 行：若父 Namespace 不存在，抛出 BadRequestException 异常。
- 第 17 至 20 行：若父 Namespace 有未发布的配置变更，不允许合并。因为，可能存在冲突，无法自动解决。此时，需要在 Portal 上将父 Namespace 的配置进行一次发布，或者回退回历史版本。
- 第 12 行：调用
- 第 21 至 30 行：获得配置变更集合 ItemChangeSets 对象。该对象，我们在 《Apollo 源码解析 —— Portal 批量变更 Item》 。
- 第 22 行：调用
ItemService#findItems(appId, env, clusterName, namespaceName)方法，获得父 Namespace 的 ItemDTO 数组。 - 第 24 行：调用
ItemService#findItems(appId, env, branchName, namespaceName)方法，获得子 Namespace 的 ItemDTO 数组。 - 第 26 行：调用
ItemsComparator#compareIgnoreBlankAndCommentItem(baseNamespaceId, baseItems, targetItems)方法，计算变化的 Item 集合。详细解析，点击方法链接查看，笔者已经添加详细注释。 - 第 28 行：设置
ItemChangeSets.deleteItem为空。因为子 Namespace 从父 Namespace 继承配置，但是实际自己没有那些配置项，所以如果不设置为空，会导致合并时，这些配置项被删除。
- 第 22 行：调用
2.3 ReleaseAPI
com.ctrip.framework.apollo.portal.api.ReleaseAPI ，实现 API 抽象类，封装对 Admin Service 的 Release 模块的 API 调用。代码如下：
3. Admin Service 侧
3.1 ReleaseController
在 apollo-adminservice 项目中， com.ctrip.framework.apollo.adminservice.controller.ReleaseController ，提供 Release 的 API 。
#updateAndPublish(...) 方法，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。代码如下：
1: /**
2: * merge branch items to master and publish master
3: *
4: * @return published result
5: */
6: @Transactional
7: @RequestMapping(path = "/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/updateAndPublish", method = RequestMethod.POST)
8: public ReleaseDTO updateAndPublish(@PathVariable("appId") String appId,
9: @PathVariable("clusterName") String clusterName,
10: @PathVariable("namespaceName") String namespaceName,
11: @RequestParam("releaseName") String releaseName,
12: @RequestParam("branchName") String branchName,
13: @RequestParam(value = "deleteBranch", defaultValue = "true") boolean deleteBranch, // 是否删除 Namespace 分支
14: @RequestParam(name = "releaseComment", required = false) String releaseComment,
15: @RequestParam(name = "isEmergencyPublish", defaultValue = "false") boolean isEmergencyPublish,
16: @RequestBody ItemChangeSets changeSets) {
17: // 获得 Namespace
18: Namespace namespace = namespaceService.findOne(appId, clusterName, namespaceName);
19: if (namespace == null) {
20: throw new NotFoundException(String.format("Could not find namespace for %s %s %s", appId, clusterName, namespaceName));
21: }
22: // 合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release
23: Release release = releaseService.mergeBranchChangeSetsAndRelease(namespace, branchName, releaseName, releaseComment, isEmergencyPublish, changeSets);
24: // 若需要删除子 Namespace ，则进行删除
25: if (deleteBranch) {
26: namespaceBranchService.deleteBranch(appId, clusterName, namespaceName, branchName, NamespaceBranchStatus.MERGED, changeSets.getDataChangeLastModifiedBy());
27: }
28: // 发送 Release 消息
29: messageSender.sendMessage(ReleaseMessageKeyGenerator.generate(appId, clusterName, namespaceName), Topics.APOLLO_RELEASE_TOPIC);
30: // 将 Release 转换成 ReleaseDTO 对象
31: return BeanUtils.transfrom(ReleaseDTO.class, release);
32: }- 第 17 至 21 行：调用
NamespaceService#findOne(ppId, clusterName, namespaceName)方法，获得父 Namespace 对象。- 若校验到不存在，抛出 NotFoundException 异常。
- 第 23 行：调用
ReleaseService#mergeBranchChangeSetsAndRelease(...)方法，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。详细解析，见 「3.2 ReleaseService」 。 - 第 25 至 27 行：若需要删除子 Namespace ，即 Portal 中选择【删除灰度版本】，调用
NamespaceBranchService#deleteBranch(...)方法，删除子 Namespace 相关的记录。详细解析，见 「3.3 NamespaceBranchService」 。 - 第 29 行：调用
MessageSender#sendMessage(String message, String channel)方法，发送发布消息。 - 第 31 行：调用
BeanUtils#transfrom(Class方法，将 Release 转换成 ReleaseDTO 对象。clazz, Object src)
3.2 ReleaseService
在 apollo-biz 项目中，com.ctrip.framework.apollo.biz.service.ReleaseService ，提供 Release 的 Service 逻辑给 Admin Service 和 Config Service 。
3.2.1 mergeBranchChangeSetsAndRelease
ReleaseService#mergeBranchChangeSetsAndRelease(...) 方法，合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release 。代码如下：
1: // 合并子 Namespace 变更的配置 Map 到父 Namespace ，并进行一次 Release
2: @Transactional
3: public Release mergeBranchChangeSetsAndRelease(Namespace namespace, String branchName, String releaseName,
4: String releaseComment, boolean isEmergencyPublish,
5: ItemChangeSets changeSets) {
6: // 校验锁定
7: checkLock(namespace, isEmergencyPublish, changeSets.getDataChangeLastModifiedBy());
8: // 变更的配置集 合 ItemChangeSets 对象，更新到父 Namespace 中。
9: itemSetService.updateSet(namespace, changeSets);
10:
11: // 获得子 Namespace 的最新且有效的 Release 对象
12: Release branchRelease = findLatestActiveRelease(namespace.getAppId(), branchName, namespace.getNamespaceName());
13: // 获得子 Namespace 的最新且有效的 Release 编号
14: long branchReleaseId = branchRelease == null ? 0 : branchRelease.getId();
15:
16: // 获得父 Namespace 的配置 Map
17: Map operateNamespaceItems = getNamespaceItems(namespace);
18:
19: // 创建 Map ，用于 ReleaseHistory 对象的 `operationContext` 属性。
20: Map operationContext = Maps.newHashMap();
21: operationContext.put(ReleaseOperationContext.SOURCE_BRANCH, branchName);
22: operationContext.put(ReleaseOperationContext.BASE_RELEASE_ID, branchReleaseId);
23: operationContext.put(ReleaseOperationContext.IS_EMERGENCY_PUBLISH, isEmergencyPublish);
24:
25: // 父 Namespace 进行发布
26: return masterRelease(namespace, releaseName, releaseComment, operateNamespaceItems,
27: changeSets.getDataChangeLastModifiedBy(),
28: ReleaseOperation.GRAY_RELEASE_MERGE_TO_MASTER, operationContext);
29: } - 第 7 行：调用
#checkLock(...)方法，校验锁定。 - 第 9 行：调用
ItemService#updateSet(namespace, changeSets)方法，将变更的配置集 合 ItemChangeSets 对象，更新到父 Namespace 中。详细解析，在 《Apollo 源码解析 —— Portal 批量变更 Item》 中。- 第 17 行：调用
#getNamespaceItems(namespace)方法，获得父 Namespace 的配置 Map 。因为上面已经更新过，所以获得到的是合并后的结果。
- 第 17 行：调用
- 第 11 至 23 行：创建 Map ，并设置需要的 KV ，用于 ReleaseHistory 对象的
operationContext属性。- 第 12 行：调用
#findLatestActiveRelease(...)方法，获得子 Namespace 的最新且有效的 Release 对象。 - 第 14 行：获得子 Namespace 的最新且有效的 Release 编号。
- 第 21 至 23 行：设置 KV 到 Map 中。
- 第 12 行：调用
- 第 26 至 28 行：调用
#masterRelease(...)方法，父 Namespace 进行发布。这块，和 《Apollo 源码解析 —— Portal 发布配置》 的逻辑就统一了，所以详细解析，见该文。
3.3 NamespaceBranchService
在 apollo-biz 项目中，com.ctrip.framework.apollo.biz.service.NamespaceBranchService ，提供 Namespace 分支的 Service 逻辑给 Admin Service 和 Config Service 。
3.3.1 deleteBranch
#deleteBranch(...) 方法，删除子 Namespace 相关的记录。代码如下：
1: @Transactional
2: public void deleteBranch(String appId, String clusterName, String namespaceName,
3: String branchName, int branchStatus, String operator) {
4: // 获得子 Cluster 对象
5: Cluster toDeleteCluster = clusterService.findOne(appId, branchName);
6: if (toDeleteCluster == null) {
7: return;
8: }
9: // 获得子 Namespace 的最后有效的 Release 对象
10: Release latestBranchRelease = releaseService.findLatestActiveRelease(appId, branchName, namespaceName);
11: // 获得子 Namespace 的最后有效的 Release 对象的编号
12: long latestBranchReleaseId = latestBranchRelease != null ? latestBranchRelease.getId() : 0;
13:
14: // 创建新的，用于表示删除的 GrayReleaseRule 的对象
15: // update branch rules
16: GrayReleaseRule deleteRule = new GrayReleaseRule();
17: deleteRule.setRules("[]");
18: deleteRule.setAppId(appId);
19: deleteRule.setClusterName(clusterName);
20: deleteRule.setNamespaceName(namespaceName);
21: deleteRule.setBranchName(branchName);
22: deleteRule.setBranchStatus(branchStatus); // Namespace 分支状态
23: deleteRule.setDataChangeLastModifiedBy(operator);
24: deleteRule.setDataChangeCreatedBy(operator);
25: // 更新 GrayReleaseRule
26: doUpdateBranchGrayRules(appId, clusterName, namespaceName, branchName, deleteRule, false, -1);
27:
28: // 删除子 Cluster
29: // delete branch cluster
30: clusterService.delete(toDeleteCluster.getId(), operator);
31:
32: // 创建 ReleaseHistory 对象，并保存
33: int releaseOperation = branchStatus == NamespaceBranchStatus.MERGED ? ReleaseOperation.GRAY_RELEASE_DELETED_AFTER_MERGE : ReleaseOperation.ABANDON_GRAY_RELEASE;
34: releaseHistoryService.createReleaseHistory(appId, clusterName, namespaceName, branchName, latestBranchReleaseId, latestBranchReleaseId,
35: releaseOperation, null, operator);
36: // 记录 Audit 到数据库中
37: auditService.audit("Branch", toDeleteCluster.getId(), Audit.OP.DELETE, operator);
38: }- 第 4 至 8 行：调用
ClusterService#findOne(appId, branchName)方法，获得子 Cluster 对象。 - 第 10 行：调用
ReleaseService#findLatestActiveRelease(namespace)方法，获得最后、有效的 Release 对象。- 第 12 行：获得最后、有效的 Release 对象的编号。
- 第 14 至 24 行：创建新的，用于表示删除的 GrayReleaseRule 的对象。并且，当前场景，该 GrayReleaseRule 的
branchStatus为 MERGED 。- 第 26 行：调用
#doUpdateBranchGrayRules(...)方法，更新 GrayReleaseRule 。详细解析，见 《Apollo 源码解析 —— Portal 配置灰度规则》 中。
- 第 26 行：调用
- 第 30 行：调用
ClusterService#delte(id, operator)方法，删除子 Cluster 相关。详细解析，见 「3.4 ClusterService」 。 - 第 32 至 35 行：调用
ReleaseHistoryService#createReleaseHistory(...)方法，创建 ReleaseHistory 对象，并保存。 - 第 37 行：记录 Audit 到数据库中。
3.4 ClusterService
在 apollo-biz 项目中，com.ctrip.framework.apollo.biz.service.ClusterService ，提供 Cluster 的 Service 逻辑给 Admin Service 和 Config Service 。
3.4.1 delete
#delete(...) 方法，删除 Cluster 相关。代码如下：
@Transactional
public void delete(long id, String operator) {
// 获得 Cluster 对象
Cluster cluster = clusterRepository.findOne(id);
if (cluster == null) {
throw new BadRequestException("cluster not exist");
}
// 删除 Namespace
// delete linked namespaces
namespaceService.deleteByAppIdAndClusterName(cluster.getAppId(), cluster.getName(), operator);
// 标记删除 Cluster
cluster.setDeleted(true);
cluster.setDataChangeLastModifiedBy(operator);
clusterRepository.save(cluster);
// 记录 Audit 到数据库中
auditService.audit(Cluster.class.getSimpleName(), id, Audit.OP.DELETE, operator);
}- 会标记删除 Cluster 和其相关的 Namespace 。代码比较简单，胖友自己看看哈。