Harbor 复制规则列表过滤功能详解从测试用例到前后端实现【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor导读复制Replication是 Harbor 在不同 Harbor 实例或仓库之间同步镜像的核心能力而规则过滤是复制规则数量较多时快速定位目标规则的必备交互。本文以官方测试用例 7-04-Proj-replication-rules-filter.md 为骨架完整还原该用例的测试目的、环境要求、操作步骤与预期结果并深入 Harbor 前端Angular Portal与后端Go API / Controller源码剖析输入字符即过滤、清空即恢复这一行为背后的模糊查询链路name~→FuzzyMatchValue帮助读者既会按步骤验证该功能也能理解其实现原理便于自行扩展或排查问题。一、测试用例背景定位与目的该用例隶属于 Harbor 仓库的复制功能测试集Group7-Replication文件名为 7-04-Proj-replication-rules-filter.md。测试目的Purpose验证复制规则replication rule的过滤功能rule filter工作是否正常。测试环境Environment需要两个 Harbor 实例同时运行且可用。这一前提是由复制功能本身的语义决定的——复制规则必须同时关联源注册表Source Registry与目标注册表Destination Registry因此至少需要一对可用的 Harbor 实例才能创建并展示完整的规则列表若需完整执行创建→过滤→删除的流程还需要管理员账号。从测试集命名7-04可以看出它属于复制Replication主题下的第 4 个用例聚焦于规则列表的检索交互而不是规则创建、执行或调度属于对复制规则管理页面的 UI/UX 与查询接口的联合验证。二、测试步骤详解2.1 系统级页面Administration - Replications步骤 1以 admin 用户登录Harbor 复制规则属于系统级资源。从后端权限定义看列出复制规则需要系统级权限rbac.ResourceReplicationPolicyActionList见 src/server/v2.0/handler/replication.go因此测试要求以管理员身份登录。步骤 2在Administration-Replications页面输入字符进行过滤随后清空过滤器系统级复制页面由 total-replication-page.component.html 承载其顶部标题为SIDE_NAV.SYSTEM_MGMT.REPLICATION内部直接嵌入了hbr-replication组件并显式设置hbr-replication [withReplicationJob]true [isSystemAdmin]isSystemAdmin [hasCreateReplicationPermission]true [hasUpdateReplicationPermission]true [hasDeleteReplicationPermission]true [hasExecuteReplicationPermission]true/hbr-replication即系统管理员在此页面拥有复制规则的增、删、改、执行全部权限。操作要点在规则列表上方的过滤输入框中输入若干字符例如规则名的一部分观察列表是否被实时收缩为名称包含该字符的规则清空输入框中的字符观察列表是否恢复显示全部规则。2.2 项目级页面Projects - Project_Name - Replication重复步骤 1-2以同样的方式在Projects-Project_Name-Replication页面重复上述操作。项目级页面复用同一个hbr-replication组件但通过projectId/projectName输入参数将作用域限定到当前项目此时规则的可见性取决于项目成员的 RBAC 权限而非全局系统权限。该用例要求在两个层级分别验证正是为了确认过滤功能在不同权限上下文、不同数据作用域下表现一致。三、预期结果与判定标准原用例定义的预期结果Expected Outcome在步骤 2 中规则可以被过滤清空过滤器后所有规则再次显示。据此可以拆解出三条可操作的验收判定标准判定点操作期望表现过滤生效输入匹配字符列表仅显示名称或按查询条件匹配的规则总数随之变化过滤还原清空输入框列表恢复显示全部规则总数恢复层级一致系统级与项目级分别验证两个页面行为一致均能过滤与还原此外若规则列表为空或输入字符无匹配项页面应显示空数据占位符REPLICATION.JOB_PLACEHOLDER一类而不是报错这也是过滤逻辑健壮性的隐含要求。四、前端实现原理500ms 防抖 模糊查询参数规则过滤框并非简单的本地数组过滤而是**服务端驱动server-driven**的查询。前端实现分布在三个文件中4.1 过滤输入组件 FilterComponent通用过滤组件 filter.component.ts 负责收集用户输入filterTerms new Subjectstring(); ... ngOnInit(): void { this.filterTerms.pipe(debounceTime(500)).subscribe(terms { this.filterEvt.emit(terms); }); }关键点500ms 防抖——用户连续输入时不会立即触发请求只有停止输入 500ms 后才真正发起查询避免每次击键都打到后端。4.2 复制页面的订阅与请求构造在 replication.component.ts 中组件在ngOnInit中订阅过滤词流this.searchSub this.filterComponent.filterTerms .pipe( debounceTime(500), distinctUntilChanged(), switchMap(ruleName { this.listReplicationRule.loading true; this.listReplicationRule.page 1; return this.replicationService.listReplicationPoliciesResponse({ page: this.listReplicationRule.page, pageSize: this.listReplicationRule.pageSize, q: ruleName ? encodeURIComponent(name~${ruleName}) : null, }); }) ) .subscribe({ ... });实现要点debounceTime(500)与 FilterComponent 的防抖叠加双重保证请求频率distinctUntilChanged()输入未变化时不去重发请求switchMap新输入到达时自动取消上一次未完成的请求避免乱序响应覆盖正确结果查询参数q采用name~关键字形式~表示模糊fuzzy匹配每次查询都会重置到第 1 页保证过滤结果从第一页开始展示。4.3 规则列表组件的兜底查询规则列表组件 list-replication-rule.component.ts 在数据加载clrLoad时同样构造查询参数const param: ReplicationService.ListReplicationPoliciesParams { page: this.page, pageSize: this.pageSize, sort: getSortingString(state), }; if (this.searchString) { param.q encodeURIComponent(name~${this.searchString}); } else { param.q getQueryString(state); }即有过滤词时按name~模糊查询无过滤词时退回普通分页查询。这也从代码层面印证了清空过滤器即恢复全部规则的实现——清空后q不再携带过滤条件后端返回完整分页数据。页面模板 replication.component.html 中过滤框的占位符文案由REPLICATION.FILTER_POLICIES_PLACEHOLDER提供并有一个刷新按钮调用refreshRules()。注意refreshRules()在已有输入时会向filterTerms推送空串触发重新查询这保证了清空并刷新后列表立即还原。五、后端实现原理从 HTTP 参数到模糊查询5.1 API Handler 层复制策略列表接口由 src/server/v2.0/handler/replication.go 中的ListReplicationPolicies实现query, err : r.BuildQuery(ctx, params.Q, params.Sort, params.Page, params.PageSize) ... if params.Name ! nil { query.Keywords[Name] q.FuzzyMatchValue{ Value: *params.Name, } } total, err : r.ctl.PolicyCount(ctx, query) policies, err : r.ctl.ListPolicies(ctx, query)处理逻辑为通过BuildQuery解析通用查询参数q即前端传来的name~xxx以及分页、排序参数若显式携带name参数则向查询关键字中注入q.FuzzyMatchValue先调用PolicyCount获取总数写入响应头x-total-count前端据此渲染分页总数再调用ListPolicies拉取当页数据。5.2 查询模型层FuzzyMatchValue定义在 src/lib/q/query.go是 Harbor 统一查询库q提供的模糊匹配包装类型。查询对象q.Query见 src/lib/q/query.go包含Keywords、Sorts、PageNumber、PageSize等字段最终由底层 ORM 层src/lib/orm翻译为 SQL 的LIKE条件实现名称的包含式匹配。5.3 Controller 层复制控制器 src/controller/replication/policy.go 中func (c *controller) PolicyCount(ctx context.Context, query *q.Query) (int64, error) { return c.repMgr.Count(ctx, query) } func (c *controller) ListPolicies(ctx context.Context, query *q.Query) ([]*model.Policy, error) { policies, err : c.repMgr.List(ctx, query) ... ps append(ps, p) // 逐个补充源/目标注册表详情 ... }Controller 将查询直接下推给复制规则管理器repMgr并在返回前通过populateRegistry为每条规则补充源注册表SrcRegistry与目标注册表DestRegistry信息——这正是规则列表中能看到来源/目标列的原因也是测试环境必须准备两个 Harbor 实例的底层依据。5.4 调用链小结综合前后端一次输入字符过滤规则的完整调用链为输入框 (hbr-filter) → FilterComponent.filterTerms (500ms 防抖) → ReplicationComponent.searchSub (distinctUntilChanged switchMap) → GET /replication/policies?qname~keywordpage1page_sizeN → ListReplicationPolicies (RBAC 校验) [src/server/v2.0/handler/replication.go] → query.Keywords[Name] FuzzyMatchValue → Controller.PolicyCount / Controller.ListPolicies [src/controller/replication/policy.go] → repMgr.Count / repMgr.ListORM 层执行 LIKE 查询 → 响应 x-total-count 规则列表 → 前端渲染规则表格清空输入框时q参数为空或null后端退化为普通分页查询从而所有规则再次显示。六、自动化测试与 API 层验证除 UI 用例外Harbor 还为复制规则提供了 Python API 测试可作为过滤功能的补充验证手段tests/apitests/python/library/replication.py封装复制规则的增、删、查等 API 操作tests/apitests/python/test_add_replication_rule.py覆盖规则创建相关流程tests/apitests/python/test_replication_from_dockerhub.py验证从 Docker Hub 拉取复制的端到端链路。通过 HTTP 接口同样可以验证过滤语义例如直接调用GET /api/v2.0/replication/policies?qname~关键字观察返回列表仅包含名称匹配的规则再以不带q的方式请求确认返回完整规则集合。这与 7-04 用例在 UI 层验证的目标一致可以在 CItests/ci中自动化执行。七、可能遇到的问题与排查建议原用例中Possible Problems: None但从实现角度实际部署中仍可能遇到以下情况现象可能原因排查方向输入字符后列表迟迟不更新防抖窗口500ms内仍在输入请求尚未发出停顿 1 秒以上观察检查浏览器 Network 面板是否出现replication/policies?q请求过滤结果不符合预期查询参数编码错误或关键字包含特殊字符确认请求 URL 中qname~xxx已被encodeURIComponent正确编码清空后列表未恢复未触发刷新事件或filterTerms未收到空串手动点击页面刷新按钮refreshRules()会推送空串并重查项目级页面看不到任何规则当前账号在项目内缺少复制规则查看权限检查项目成员角色及rbac.ResourceReplicationPolicy相关权限配置规则列表无源/目标注册表信息关联注册表已被删除或不可达在Administration-Registries中确认源/目标端点状态八、总结7-04 用例验证的规则过滤看似只是列表页的小交互背后却串联了 Harbor 的三层架构Angular Portal 的防抖输入与switchMap请求管理、Go 后端q.FuzzyMatchValue的模糊查询语义、以及 Controller→ORM 的参数下推。理解这条链路后读者不仅能在系统级与项目级页面熟练验证过滤功能还能通过GET /api/v2.0/replication/policies?qname~关键字在 API 层直接复用该能力依据 src/lib/q/query.go 中的查询模型扩展到其他支持q参数的资源列表在排查过滤不生效 / 列表不恢复类问题时快速定位是前端请求构造、后端参数解析还是权限校验环节的问题。相关可继续深入阅读的仓库文件测试用例tests/testcases/Group7-Replication/7-04-Proj-replication-rules-filter.md前端过滤组件src/portal/src/app/shared/components/filter/filter.component.ts前端复制页面src/portal/src/app/base/left-side-nav/replication/replication/replication.component.ts后端 APIsrc/server/v2.0/handler/replication.go后端控制器src/controller/replication/policy.go查询模型src/lib/q/query.go【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
