Fleet React/TypeScript 前端代码评审指南frontend-reviewer 规范与实践【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet本文以 Fleet 开源仓库中 frontend-reviewer 评审 Agent 定义 为骨架系统梳理 Fleet 前端React/TypeScript SCSS在类型安全、数据请求、组件结构、样式命名、API 服务层与可访问性上的代码约定并逐条对照frontend/目录下的真实源码给出依据。读完本文你既能掌握一套可直接落地的前端评审 checklist也能理解 Fleet 前端代码为何采用这些模式的底层原因从而在自己的 PR 提交或代码评审中快速对齐官方规范。一、frontend-reviewer一个为 Fleet 前端量身定制的评审 Agent在 Fleet 仓库的 .claude/agents/frontend-reviewer.md 中定义了一个名为frontend-reviewer的评审 Agent。它并非空泛的通用评审提示词而是明确声明为 a frontend code reviewer specialized in Fleets React/TypeScript codebase即专门针对 Fleet 特有模式和约定的代码评审器。从该文件的 frontmatter 可以看到其运行配置字段取值含义namefrontend-reviewerAgent 名称便于按名调用descriptionReviews React/TypeScript frontend changes in Fleet for conventions, type safety, component structure, and accessibility评审覆盖范围代码约定、类型安全、组件结构、可访问性toolsRead, Grep, Glob, Bash评审所需的四类工具读文件、正则搜索、路径匹配、执行命令modelsonnet推荐的模型规格该文件的description特别强调 Run PROACTIVELY after modifying frontend files意味着在改动frontend/下任何文件之后都应主动触发一次评审而不是等到 CI 或合并前才检查。这一主动运行的机制配合下面六个评审维度构成 Fleet 前端质量保障的第一道人工/Agent 防线。二、TypeScript 严格性拒绝any用类型守卫收窄评审清单的第一项是 TypeScript 严格性共三条硬性要求不出现any类型。当类型不确定时应使用unknown配合类型守卫type guards或定义明确的 interface而不是用any一刀切地放弃类型检查。正确使用 frontend/interfaces 下的领域接口。Fleet 为前端数据模型建立了独立的接口目录涵盖设备、用户、策略、软件、MDM 等核心领域对象例如host.ts 中的IHost设备user.ts 中的IUser用户以及 policy.ts、software.ts、mdm.ts、team.ts 等评审要求组件与页面优先复用这些领域接口而不是在局部重复定义结构相近的裸对象类型。访问可空字段前必须先做类型收窄type narrowing。例如从 API 返回的IHost中某个字段可能是null读取前必须通过判空或收窄逻辑排除null/undefined禁止在未收窄的情况下直接访问。从仓库看frontend/interfaces 目录维护了 50 个领域类型文件这种接口集中管理、组件按需引用的做法正是类型安全的基础——领域模型一旦变更编译期即可暴露所有受影响的调用点这也是为什么评审会优先关注是否使用了正确的 interface。三、React Query 数据请求模式查询与变更分离Fleet 前端的数据请求以 TanStack React QueryuseQuery/useMutation为统一范式评审重点如下读取数据使用useQuery且必须提供正确的[queryKey, dependency]数组query key 与依赖项并通过enabled选项控制查询何时发起例如依赖某个参数就绪后才请求。写操作使用useMutation而不是在useQuery里做副作用。禁止在 React Query 适用场景下手动useState/useEffect去拉取数据。若发现手写请求 useEffect useState 存结果的模式应改写为useQuery以获得缓存、重试、失效重取等开箱能力。仓库中组件层大量遵循这一模式例如 SoftwareInstallDetailsModal.tsx 等软件安装详情弹窗组件即组合使用useQuery与useMutation处理安装状态的查询与命令下发。此外 frontend/hooks 目录还沉淀了一批领域化的自定义 Hook如 useQueryTargets.ts、useTeamIdParam.ts把查询 目标选择 团队参数这类高频逻辑封装成可复用单元评审时同样会检查是否优先复用了这些 Hook。四、组件结构四文件模式与 generate 脚手架4.1 四文件模式Fleet 前端的每个组件目录遵循固定的四文件结构ComponentName/ ├── ComponentName.tsx # 组件实现 ├── _styles.scss # 组件专属样式下划线前缀 ├── ComponentName.tests.tsx # 组件测试 └── index.ts # 统一出口re-export这一结构在仓库中大量组件目录里可见例如 frontend/components/ActionsDropdown、frontend/components/Card 等目录都包含同名组件文件、index.ts出口与对应测试。4.2 用 generate 脚本生成新组件文档要求新组件通过 frontend/components/generate 脚手架创建./frontend/components/generate -n Name -p path从该 Python 脚本源码可以看到它实际执行的动作名称校验validate_name要求名称长度大于 1、既非全小写也非全大写、且首字母大写——即必须是规范的 PascalCase否则提示Enter a PascalCase name派生 BEM 基类名get_component_classname用正则[A-Z][^A-Z]*按大写字母拆分单词并转小写后用-连接例如HostDetails→host-details这一派生结果正是后续 SCSS 的baseClass一次性生成五个文件index.ts内容为export { default } from ./Name;、Name.tsx、_styles.scss、Name.tests.tsx预置testing-library/react的 render/screen 骨架、以及Name.stories.tsxStorybook 故事骨架。命令行参数支持-n/--namePascalCase 组件名必填、-p/--output_path输出目录默认当前目录、-o/--overwrite_directory同名目录存在时覆盖重建默认关闭。用脚手架生成可以确保每个新组件从一开始就具备完整目录骨架、样式文件与测试文件避免组件写完了才发现缺index.ts之类的遗漏。4.3 导出方式文档要求新代码使用**命名导出named exports**而非默认导出。需要留意的是脚手架的index.ts模板当前以export { default } from ./Name;形式做默认导出转发因此评审时需结合具体组件文件确认导出方式是否符合规范这也是评审清单中值得单独点出的一处约定与模板现状的差异。五、SCSS 与 BEM 命名约定样式层面Fleet 采用SCSS BEMBlock Element Modifier约定评审检查点非常明确组件 SCSS 中在顶部定义const baseClass component-name;作为 BEM 的 Block 基准元素Element写作${baseClass}__element例如host-details__title修饰符Modifier写作${baseClass}--modifier例如button--disabled组件样式统一放在_styles.scss文件中下划线前缀使其成为 SCSS partial便于use组合进全局样式。这套约定与 4.2 节的脚手架联动generate脚本会根据组件名自动推导baseClassHostDetails→host-details并在生成的_styles.scss中预置.{base_class_name} {}占位保证组件实现与样式命名的基准一致。评审时如果看到硬编码的样式类名或嵌套过深的 CSS 选择器就属于违反 BEM 约定应改为基于baseClass的模板字符串组合。六、API 服务层统一走 sendRequest 与端点常量Fleet 前端不直接在各组件里写裸fetch而是通过统一的服务层发起请求。评审要求使用 frontend/services 导出的sendRequest系列函数发起 HTTP 请求。从 frontend/services/index.ts 源码可见服务层实际导出了四个变体sendRequest基础请求定义于该文件第 70 行附近sendRequestWithProgress带进度回调用于上传/下载等场景sendRequestWithHeaders可自定义请求头sendRequestWithProgressAndHeaders进度 请求头组合业务封装按领域拆分在frontend/services/entities/下例如 hosts.ts、policies.ts、config.ts组件层只依赖这些领域 service不直接接触传输细节。端点字符串来自 frontend/utilities/endpoints.ts 的常量。该文件以const API_VERSION latest开头将版本前缀统一收敛到一个常量中再以ACTIVITIES、CONFIG、GLOBAL_POLICIES等具名常量或HOST_PAST_ACTIVITIES(id)这类函数式端点导出全部 REST 路径禁止在组件里手写 URL 字符串。正确处理 API 错误。请求失败的场景必须有错误分支提示信息或降级 UI不能静默吞掉异常。这一层设计的价值在于端点的增删改、请求头策略、错误处理策略全部集中管理前端评审时只需确认新请求是否走了sendRequest 端点常量即可快速判断是否符合架构约定。七、可访问性Accessibility评审清单的可访问性维度包含三点交互元素必须有 ARIA 属性。对自定义实现的可点击元素如按钮化的div、下拉、弹窗需补充role、aria-label、aria-expanded等属性让屏幕阅读器能正确解释其语义与状态。支持键盘导航。Tab 顺序合理Enter/Space 可触发主操作焦点在弹窗关闭、面板切换等场景下能被正确管理焦点陷阱与焦点归还。优先使用语义化 HTML 元素。能用button、nav、main、dialog表达的结构就不要退化为div堆叠天然获得可访问性与 SEO 收益。在 Fleet 这类以表格、表单、弹窗为主的管理后台中可访问性问题的典型形态包括图标按钮缺少aria-label、可点击行没有键盘等价操作、弹窗打开后焦点未移入。评审时需逐项核对上述三点尤其是新增交互组件时。八、评审输出格式按严重级别分级先堵后修frontend-reviewer 的最终产出不是笼统的意见列表而是按严重级别三级组织的评审结论Blocking阻塞级——合并前必须修复类型错误、破坏既有模式的写法、可访问性违规。这类问题会直接影响代码正确性或用户可达性应无条件返工。Important重要级——应当修复违反代码约定、缺失类型定义。例如该用useQuery却手写了数据请求、新组件没按四文件结构组织、漏了 interface 类型标注。Minor次要级——风格细节与建议命名微调、注释补充、小的重构建议不阻塞合并但值得记录。这套分级机制的价值在于可执行性评审者把结论按影响面排序开发者按 Blocking → Important → Minor 的顺序处理既保证质量底线又避免满屏 nit 淹没真问题。在 PR 评审中可以直接套用这三级模板组织评论让问题分级成为团队共识。九、把这套规范用起来将以上约定汇总可以形成一张可复用的 Fleet 前端评审 checklist类型无any复用frontend/interfaces领域接口可空字段先收窄再访问数据请求读用useQuery含正确 query key 与enabled写用useMutation不手写请求副作用组件四文件结构组件 /_styles.scss/ 测试 /index.ts新组件用./frontend/components/generate -n Name -p path生成命名导出样式顶部定义baseClassBEM 的__element与--modifier样式只进_styles.scssAPI统一sendRequest系列函数端点常量取 endpoints.ts请求必有错误处理可访问性ARIA 属性、键盘导航、语义化 HTML输出Blocking / Important / Minor 三级先修复阻塞项。对于参与 Fleet 前端开发或向 Fleet 提交 PR 的工程师这套以 frontend-reviewer 为代表的规范既是评审标准也是编码时的事前约束——写代码时逐条对照评审时的 Blocking 项自然大幅减少。而对于任何 React/TypeScript 项目文中接口集中管理、请求统一收敛、样式 BEM 化、组件目录模板化、评审分级化的方法论同样具备直接的可迁移价值。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考