FlexLB 开发规范
让了解业务但首次接触该类的人,能从代码和相邻注释直接读懂流程、状态及清理责任。 以真实代码和用户当前要求为依据;简单修改直接落实,不为套流程扩大任务。
统一术语与命名
新增、修改或审核类名、方法名、字段名、状态名及架构说明时,读取
FlexLB 开发术语与命名约定,按业务含义选择术语。
重点区分调度、选址、路由发布、交付、抢占、取消、资源释放和请求清理,不能互相替代。
同一个概念使用同一个词;不同含义使用不同名称,不用 Placement 等宽泛词统称多个步骤。
术语表中的现有类名是定位示例,不是新增抽象的要求;旧名迁移只处理当前授权范围,
不能机械替换无关的缓存淘汰、外部协议字段、配置键或监控指标。
开始修改前
本技能及相关开发技能统一维护在 FlexLB 的 skills/,以仓库版本为准。
仓库根目录的 .agents/skills/flexlb-development 通过相对符号链接指向本技能,
让仓库根目录、rtp_llm 和 rtp_llm/flexlb 下的 Codex 都能发现同一入口。
- 从当前工作区定位
rtp_llm/flexlb,阅读适用的AGENTS.md和相关模块说明。 这些文件是仓库约定的来源;本技能不固化会随重构变化的类名、配置项或模块职责。 - 查看工作区和暂存区,区分用户既有改动与本次任务。不能通过恢复文件、整文件覆盖或 全量暂存清理别人的改动;基于当前代码修改,不假设工作区等于 HEAD。
- 阅读实际入口、关键调用方、被改类及相关测试。架构问题按需阅读
docs/architecture/和当前适用的设计说明,区分设计目标、历史提案和已实现行为。 - 先明确要改变的行为与必须保持的语义。用户只要求解释、评审或方案时不直接改逻辑; 只要求命名、排序或排版时不顺带修改生命周期、重试或同步策略。
- 跨模块职责调整按需读取 workflow-first-design, 局部实现按需读取 evidence-first-implementation; 不把小修改强制升级成架构设计。
由 AI 理解流程,再组织代码
创建或修改任何具名类(包括有独立职责的内部类)时,先判断是否需要类说明,再改成员或实现。 这也适用于旧类和仅调整成员顺序的修改,不限于新增类或实质重构:
- 旧类先读实现和调用方,为需要说明的类补齐缺失注释,修正已经过时或过长的说明; 原说明准确且简洁时保留,不为走流程重写。
- 新流程类先写清职责和预期主流程,再实现。类说明只概括本类负责的业务,不代替设计材料。
- 依据确认后的流程组织成员并实施本次修改,完成后再核对说明与代码一致。 发现旧注释和实现矛盾时先查明实际契约,不能为迎合注释擅自改变现有行为。
流程类通过实现和调用方确认以下问题,但不要将这份检查清单全部抄进类注释:
- 类负责的业务对象及边界,哪些独立入口会触发它。
- 从进入、处理、等待到结束的主要步骤;在哪个线程执行,哪里会异步交接。
- 关键状态代表什么,谁修改,何时失效;失败和取消后谁继续清理。
start、stop、close的真实效果:启动什么、停止接纳还是停止执行、是否等待、 最终释放哪些资源。不能只看名字假设生命周期。
类 Javadoc 默认只写 1–3 句话,通常是职责、主流程、一个确有必要的关键边界。 使用简洁的多行格式;不要罗列全部方法、字段、状态、异常分支或调用链,不逐行翻译实现, 也不堆叠“本类不负责什么”。命名和字段已自解释、没有自定义行为的简单 record、DTO 和枚举 可以没有类注释,不为了满足形式重复代码。有单位、特殊取值、身份约束、校验、资源或生命周期 语义时需要说明;局部约束优先放在相应字段或方法旁。不为数据类编造启动、停止流程。 有必要的局部细节放在对应代码附近,避免类注释盖过主体逻辑。 流程变化时同步修改说明;本次未涉及的类不顺手批量添加模板注释。
例如,只有在实现确实满足时才这样说明:
/**
* 执行请求任务:接收并处理请求,停止接收后等待已有工作结束,再释放执行资源。
* 用户响应回调在请求锁外执行。
*/
成员顺序与人类阅读顺序
- 字段及初始化块在前,构造器随后,方法按
public → protected → 包级 → private分组,内部类型放在方法之后并递归整理。 - 各可见性组内,按类的真实流程放置业务入口及相关方法。多个独立入口的顺序由 AI 结合类流程说明判断,不能用字母顺序、方法长度或调用次数代替业务判断。
- 字段优先呈现常量、核心依赖与配置,再呈现运行状态、索引与缓存、诊断信息; 相关成员成组留白。但同类初始化操作的相对顺序、实例字段顺序和 Lombok 构造器参数顺序必须保持。受到这些约束时用空行或简短分组说明改善阅读。
- 方法名、变量名直接说明保存的数据或实际动作。避免用模糊的 ownership、terminal、 settlement 等词统称不同职责;已有领域术语需要准确指向具体对象或行为。
- 将用户已确认的流程顺序作为修改依据;不要让自动排序反复打乱人工安排。
排序脚本的真实边界
使用前检查仓库内 tools/order_java_members.py --help 和实现,避免依赖过期能力描述。
现有版本按成员类型、可见性和源码调用关系排序;不理解业务重要性,也不解析自然语言
流程或 MemberOrder 声明。类注释由 AI 理解后写,当前不能声称脚本会按该注释排序。
若要让脚本执行类注释中的流程,需在用户授权的工具改动范围内实现明确的声明格式、 方法签名匹配、缺失或歧义诊断和测试;不能仅写入注释就宣称能力完成。 排序前先预览影响范围,特别检查重载、回调、递归调用与多个独立入口。
功能与并发修改
- 一个状态表达一件事。引擎正在执行、占用本地容量、已收到完成反馈、Future 已完成、 请求已清理归档是不同事实;不能以其中之一替代其他事实。
- 保留请求、一次尝试、Endpoint generation 和资源句柄的准确身份约束。 旧回调不能修改新尝试,释放操作不能指向被替换的资源记录。
- 明确每次资源获取、物理发布、执行器接纳和清理的责任交接点。 提交成功不等于发送成功,取消发出不等于资源释放,完成响应不等于全部清理结束。
- 不在请求锁内执行用户回调、网络等待或昂贵计算。涉及锁覆盖与交接时, 沿真实路径核对锁顺序、异常分支和回调重入,不能仅凭“有锁”宣称安全。
- 执行器负责它实际接纳的任务。优先复用标准执行器、Future、现有队列及线程归属, 避免再手工维护一套重复的全局任务计数或集合。确有必要新增跟踪时先解释其覆盖的 独有事实,以及登记、交接、拒绝、合并和释放如何集中管理。
- 队列为空、线程处于 WAITING 或某个瞬间 activeCount 为零,都不能独立证明清理结束。 关闭方案必须覆盖同步调用方、已接纳工作、后续任务和晚到回调;关闭执行器前确认 谁还会提交任务。不能用固定睡眠、过早 shutdown 或忽略拒绝来掩盖交接问题。
- 保持当前契约中的策略选择、等待条件、重试预算及超时语义。标准机制不能直接替换时, 解释具体阻碍;不能为删除计数或减少类数偷偷改变业务行为。
- 同步清理被替代的入口、包装、字段和测试夹具;不保留两套互相竞争的状态来源。
验证与交付
按改动风险验证,使用当前模块配置中的真实类名和测试工具:
提交 FlexLB 改动前必须执行并通过仓库的 pre-commit;不能用单独运行格式脚本代替。 从仓库根目录运行
python3 -m pre_commit run --hook-stage pre-commit,检查本次暂存内容。 每个 checkout 首次使用时安装 pre-commit 并设置git config --local core.hooksPath .githooks, 让普通git commit自动执行相同检查。不得用--no-verify、SKIP或停用钩子绕过失败。FlexLB Java 钩子检查输入文件的成员顺序及本次新增、修改类的 Javadoc 是否存在、 有用途或流程摘要并采用多行格式。无自定义行为的简单 record、纯字段 DTO 和简单枚举 免于强制类注释;结构简单不保证语义自解释,隐含约束仍须审核。未触及的旧类不追溯补齐。Spotless 对整个 Maven reactor 做只读校验。钩子在隔离的 Python 环境安装解析器,不依赖个人目录。
类说明是否准确、是否简短、是否覆盖真实流程仍须 AI 和人工审核;不能声称 pre-commit 可以理解业务语义或完全阻止绕过本地 Git 钩子的提交。
命名、注释、排序等低风险修改不机械新增行为测试。成员移动应核对方法体、注解、 注释归属、初始化操作和 Lombok 参数顺序;语法树检查不等于完整行为等价证明。
审核本次触及的类是否已有准确、简短的类说明,成员组织是否对应说明中的流程; 删除复述实现或与其他说明重复的长段文字,不能以增加注释行数代替可读性改善。
并发或清理修改覆盖接纳与关闭竞争、后续工作交接、提交拒绝、重复通知、取消、 晚到回调和部分失败。优先用锁存器或屏障构造交错,不靠随机等待碰运气。
从
rtp_llm/flexlb使用 Maven Wrapper。针对受影响模块和测试执行验证,例如:./mvnw -pl flexlb-sync -am test -Dtest=<实际测试类> -Dsurefire.failIfNoSpecifiedTests=false ./mvnw spotless:check -Pspotless-check代码修改完成前按仓库要求运行整个 Maven reactor 的 Spotless 检查,不能拿模块检查 冒充全量通过。成员排序还应运行脚本的检查模式;改脚本时运行其真实回归测试。 脚本依赖和命令以仓库 README、requirements 和
--help为准。格式化只处理授权范围,遵守当前会话的文本补丁工具要求。全量检查遇到无关改动时, 查明原因并如实报告,不为让检查变绿覆盖用户工作或无边界扩展格式化范围。
架构或行为改变时更新相关现有架构说明;局部改名和排版不新建大篇设计材料。
用户要求单独提交纯格式改动时,不能整文件暂存夹带已有功能改动。必要时在隔离工作树 基于提交基线重现格式转换,审核实际提交树,再保留原工作区的功能修改。 不未经授权改写历史、清空暂存区、推送或创建额外提交。
交付说明具体改动、执行过的验证、失败或未完成项。将“读过源码”“测试通过”与 “真实环境验证”分开;不要把脚本能力、设计方案或局部测试描述成已经全面落地。