后端前端数据分析数据可视化【免费下载链接】growthbookOpen Source Feature Flags, Experimentation, and Product Analytics项目地址https://gitcode.com/gh_mirrors/gr/growthbook点击查看免费下载本文基于 GrowthBook 仓库中的 packages/front-end/AGENTS.md 展开系统讲解其前端开发规范在修改任何前端代码前必须阅读的四份详细指南、/ui/设计系统优先的组件层级、权限控制前后端预测必须与端点一致的强制要求及其测试落地方式以及 Next.js Agent 规则块的维护机制。读完本文你将掌握在该仓库中编写前端代码的完整约定从组件选型、尺寸语义、商业化功能门控到权限检查的双测校验parity test与数据获取的标准模式。一、文档定位根规范 前端专项补充packages/front-end/AGENTS.md 的第一条规则就是先应用仓库根的 AGENTS.md。根规范定义了全局性的构建与开发命令如pnpm install、pnpm setup、pnpm --filter front-end test使用 Vitest、pnpm --filter front-end type-check、Monorepo 结构、包间导入边界front-end 只能从 shared、sdk-js、sdk-react 导入和通用代码约定TypeScript strict 模式、Zod 作为类型源头、禁止用下划线前缀压制 lint 等。在此之上前端专项规范只补充前端特有的约束并且明确指出在修改前端代码之前必须先阅读相关的详细指南。指南按主题拆分为四份分别覆盖不同关注点关注点对应指南仓库根相对路径React、UI 组件、Bootstrap 迁移.agents/guides/frontend/react-patterns.md数据获取、mutation、缓存刷新、错误处理.agents/guides/frontend/data-fetching.md权限与商业化功能门控.agents/guides/permissions.md标签、标题、按钮、正文的文案与大小写.agents/guides/ui-copy-style.md这四份指南不是可选的背景阅读而是改哪个领域就先读哪份的硬性前置条件。下面逐一深入。二、UI 组件层级先/ui/再 Radix最后才是自建前端规范的核心要求是一句话优先使用/ui/设计系统组件其次才是 Radix Themes 或自定义 UI不要引入新的 Bootstrap 用法。 这条规则在 react-patterns.md 中被展开为四级优先级/ui/设计系统组件首选——为 GrowthBook 专门构建的组件提供统一的样式与行为。radix-ui/themes次选——用于布局原语Flex、Box、Grid、Text、Heading以及尚未被设计系统封装的组件。components/现有领域组件第三级——先检查packages/front-end/components/中是否已有可复用的领域组件。新建组件最后手段——在动手写一次性组件前先自问这个模式是否可在别处复用如果它是通用而非领域相关的应提议将其加入/ui/而不是内联实现。设计系统当前提供的组件共 26 个Avatar、Badge、Button、Callout、Checkbox、ConfirmDialog、DataList、DropdownMenu、ErrorDisplay、Frame、HelperText、Link、LinkButton、Metadata、Pagination、Popover、PremiumCallout、RadioCards、RadioGroup、Select、SplitButton、Switch、Table、Tabs、Tooltip。例如表单类控件的典型写法import { Button } from /ui/Button; import { Badge } from /ui/Badge; import { Checkbox } from /ui/Checkbox; import { Select } from /ui/Select; import { Tabs } from /ui/Tabs;尺寸属性统一的 T-shirt 尺寸梯度所有/ui/组件的 size 属性共用一套 T-shirt 尺寸梯度定义在 packages/front-end/ui/sizes.ts 中。从源码可以看到完整的尺寸词汇表export type TshirtSize xs | sm | md | lg | xl | 2xl; export type SizeS extends TshirtSize S; const RADIX_SIZE { sm: 1, md: 2, lg: 3, xl: 4, } as const;使用模式是声明子集、单点映射组件在自己的 props 上声明它支持的尺寸子集如size?: Sizesm | md只在传给 Radix 原语的那一处调用radixSize(size)完成映射。指南强调三条纪律只支持子集不做重命名——给某组件加一档尺寸只是一字之改改某档含义则改RADIX_SIZE所有组件一次联动。禁止 Radix 数字size2和sizemedium之类的词——统一走 T-shirt 命名。类型即护栏当某个 Radix 原语缺少你映射的尺寸档时radixSize的返回类型会让透传处编译失败。这是护栏在正常工作应缩小子集或就地处理该档并注释原因绝不强转。xs和2xl没有共享语义由使用它们的组件自行映射例如只有 Badge 合成了xs。Bootstrap 迁移对照表Bootstrap 类名属于遗留用法新代码禁止使用。指南提供了完整的迁移对照修改到含 Bootstrap 的代码时遵循小改动不新增、新功能全用设计系统、重构时顺手迁移的原则Bootstrap 类名替代方案btn btn-primary/ui/Button的Buttonbtn btn-outline-*Button variantoutlinebadge bg-*/ui/Badge的Badgeform-check/form-switch/ui/的Checkbox或Switchnav nav-tabs/ui/Tabs的Tabstable/ui/Table的Tablealert alert-*/ui/Callout的Calloutdropdown/ui/DropdownMenu的DropdownMenud-flexradix-ui/themes的Flexd-none/d-block条件渲染或 CSSmb-*/mt-*/mx-*Box mb3或 style 属性row/col-*radix-ui/themes的Gridtext-center/text-endText aligncenter或 CSS商业化功能门控与常用 Hooks前端还有一套标准的上下文 HooksContext Provider 位于packages/front-end/services/useUser()——访问用户上下文、组织、权限其中hasCommercialFeature(feature-name)用于检查商业化功能是否可用高级功能统一用PremiumTooltip commercialFeaturefeature-name包裹以显示升级提示useEnvironments()——获取可用环境useDefinitions()——访问 metrics、features、segments 等全局定义useAuth()——认证状态提供 mutation 入口apiCall()。商业化功能标识符定义在packages/shared/src/enterprise/license-consts.ts。三、数据获取模式useApi / apiCall / mutateDefinitionsdata-fetching.md 规定前端数据层完全基于 SWR读用useApi()位于 packages/front-end/hooks/useApi.ts写用useAuth()提供的apiCall()所有请求自动作用域到当前组织。useApi()的基本用法与选项import useApi from /hooks/useApi; // 简单读取带 query 参数 const { data, error, mutate } useApi{ items: ItemInterface[] }(/items); useApiResponse(path, { shouldRun?: () boolean, // 条件执行如仅当已认证或已有 id 时才请求 autoRevalidate?: boolean, // 默认 truefocus/reconnect 时重新验证 orgScoped?: boolean, // 默认 true缓存 key 加 orgId 前缀 });关键约定条件获取用shouldRun控制请求时机例如useApiFeatureResponse(/feature/${featureId}, { shouldRun: () !!featureId })。关闭自动重验证表单编辑类数据传autoRevalidate: false避免打字时被后台刷新打断。Mutation 后必须手动刷新缓存await apiCall(/items, { method: POST, body: JSON.stringify(formData) })成功后调用await mutate()涉及全局定义metrics、features、segments的数据则改用useDefinitions()的mutateDefinitions()。组织作用域每个请求自动附带Authorization: Bearer token与X-Organization: orgId头缓存 key 以orgId::为前缀因此切换组织会自动使全部缓存失效。乐观更新先mutate(newValue, false)立即更新缓存不触发重验证apiCall成功后再await mutate()拉取真值失败则回滚。错误处理三条标准路径——try/catch 配合本地 error state、Modal的submit内 throw 由 Modal 自动展示、useApi返回的error直接驱动错误视图配合设计系统的ErrorDisplay。根 AGENTS.md 中对该模式也有浓缩表述读用useApiT(/endpoint)SWR 封装、org 作用域缓存写用apiCall(/endpoint, { method: POST, body: JSON.stringify(data) })缓存刷新用mutate()或mutateDefinitions()。四、权限控制预测必须与端点一致这是 packages/front-end/AGENTS.md 中最具强制性的部分。规范要求每一个权限控制必须同时满足三点尽可能共享服务端授权规则无法直接共享时把预测逻辑放进纯辅助函数例如 packages/shared/src/permissions/controlAuthority.ts。原则是控制端UI 按钮是否可点的权限预测必须来自与端点同一套规则而不是在页面或组件里内联推导——一处内联预测就会随时间漂移出它所预测的端点。两个测试都必须覆盖packages/back-end/test/api/permission-prediction-parity.test.ts——覆盖权限原子permission atom层面即控制端预测与服务端规则的一致性packages/front-end/test/footprintParity.test.ts——覆盖环境足迹environment footprint层面即前端计算这次变更会触及哪些环境的逻辑与 shared 包的共享实现一致。使用独立的、有区分度的测试夹具fixtures——期望值必须独立给出不能通过被测实现本身推导期望值否则实现错了测试也跟着错等于没有测试。从源码可以看到这两个测试确实按此设计permission-prediction-parity.test.ts直接用角色构建Permissions对象纯进程内检查、无数据库并用共享的OPERATION_ORACLE/PERSONA_IDS夹具驱动——与permission-matrix-revision-entities测试驱动真实端点用的是同一张表从而保证控制端与端点不可能在不让 CI 失败的情况下不一致。footprintParity.test.ts则导入 shared 包中的featurePublishFootprint、revertFootprint、serveFootprint、archiveFootprintForControl、NO_ENVIRONMENT_BINDING等足迹函数与前端/services/features中的getEnabledEnvironments、getRevisionPublishEnvs等辅助函数做逐用例对照。为什么环境足迹如此重要flag-family 授权模型AGENTS.md 要求参考 .agents/guides/flag-family-authority.md 来理解授权规则。该指南给出了标志家族Feature Flags、Configs、Constants、Saved Groups权限判断的四个名词任何一个选错都会产生该拒绝时通过、该通过时拒绝的检查名词回答的问题取值来源Verb动词用哪个原子draft、review、publish、revert、delete、create、bypass来自操作本身而非调用者角色Scope作用域哪个项目的授权适用来自实体本身若变更涉及迁移来自目标项目Footprint足迹变更实际到达哪些环境来自变更内容而非实体Basis基准问题针对哪个状态线上实体、revision 快照或恢复后的状态其中几个关键设计值得展开编辑不是一个动词一次变更最多有两个独立的授权问题——Draft项目作用域不触及任何环境和 Publish环境作用域才是真正到达用户的部分。因此用户能不能编辑这个不是良定义的问题起草者可以提交自己无权发布的草稿发布者可以落地自己没写的变更。前端条件渲染时按钮各查各的原子如permissionsUtil.canEditFeatureDrafts(feature)与permissionsUtil.canPublishFeature(feature, [production])。足迹从变更推导绝不从实体推导例如 Feature Flag revision 的足迹是规则发生变化的生效环境 本次启停的环境Saved Group 不分区足迹为空revert 的足迹是恢复状态与当前线上不同的环境。空足迹意味着此操作不受环境约束检查平凡地通过——这对 Saved Group 和提交草稿是正确的但在别处空足迹就是安全漏洞。这正是指南所说的错误的检查读起来最像正确的根源。NO_ENVIRONMENT_BINDING哨兵shared 包中存在这个显式标记让这里就是没有环境绑定的意图在调用点上一目了然指南明确警告永远不要为了凑类型而误传空数组[]。动词→权限的映射只有一处shared/permissions/revisionPermissions中的REVISION_PERMISSIONS[model][action]任何地方不得重新推导。规则的分层归属也明确两端共享的规则放shared/permissions控制端能展示什么的预测放shared/permissions/controlAuthority绝不在页面内联服务端强制执行放back-end/src/revisions/*Authority.ts。权限检查的标准写法按 permissions.md权限系统分三层全局manageTeam、manageBilling、项目作用域manageFeatures、createMetrics、环境作用域publishFeatures、runExperiments。前端首选usePermissionsUtil()的具体方法而非裸布尔字段const permissionsUtil usePermissionsUtil(); // 项目作用域检查 if (!permissionsUtil.canCreateFeature({ project: prj_123 })) { return NoAccess /; } // 环境作用域检查——传入变更实际触及的环境而不是组织的全部环境 if (!permissionsUtil.canPublishFeature(feature, changedEnvs)) { return NoAccess /; }权限与商业化功能是两道独立的门用户可能有权限但组织套餐不含该功能。前端组合写法为hasCommercialFeature(feature-name) permissionsUtil.canDoSomething()。最佳实践还包括权限检查尽早做在任何落盘操作之前不硬编码角色判断user.role ! admin这类写法被明确列为反面示例没有edit动词——内容变更 draft publish起草查canEditFeatureDrafts落地查canPublishFeature。五、UI 文案规范双层大小写规则ui-copy-style.md 定义了全仓库统一的用户可见文案规则前端标签/标题/按钮后端 API 错误消息同理核心是两层规则Heading元素用 Title CaseData Source Settings其余一切用 sentence case标签、按钮、占位符、提示文本、正文包括后端的错误与校验消息——那里没有标题所以全是 sentence case如throw new Error(Feature key must be unique within the Project)。唯一的覆盖例外是命名资源永远 Title CaseGrowthBook绝不写作 Growthbook、Visual Editor、North Star、Bandit、Data Source、Fact Metric、Feature Flag用户可见文案用全称不简写为 Feature 或 Flag、Saved Group、SDK Connection、Experiment Template、Experiment Decision Framework、ProjectAll Projects 是固定作用域标签、Constant、Config。注意 Config 与 Constant 的双重身份指 GrowthBook 资源时 Title Case指普通配置文件或不变化值时小写Project 在大查询或 GCP 语境下仍是小写普通名词。技术标识符experiment key、API key、attribute、token在行文中保持小写。六、Next.js Agent 规则块由next dev自动维护packages/front-end/AGENTS.md 末尾有一段由注释包裹的!-- BEGIN:nextjs-agent-rules --块内容值得单独说明因为它体现了该仓库对 AI Agent 协作环境的工程化处理这是你不认识的那个 Next.js——该版本存在破坏性变更API、约定和文件结构都可能与训练数据不同。写任何代码前先阅读node_modules/next/dist/docs/下相关指南从本文件所在目录解析在 monorepo 中仓库根目录可能看不到next包并注意弃用警告。该块由next dev写入并重新追加生成逻辑可对照node_modules/next/dist/server/lib/generate-agent-files.js验证。由此产生一条明确的维护纪律从 diff 中删除它只会让next dev重新生成同一个未提交变更把它随工作一起提交才能保持工作树干净。换句话说看到这段内容出现在变更里是预期行为不应作为脏文件处理。七、如何验证你的改动符合规范结合根 AGENTS.md 的命令体系一次符合前端规范的改动应能通过以下检查pnpm --filter front-end type-check # TypeScript 严格检查含 ui/sizes.ts 的尺寸类型护栏 pnpm --filter front-end test # Vitest包含 footprintParity.test.ts pnpm --filter back-end test # Jest包含权限 parity 测试 pnpm lint # ESLint 自动修复含导入边界检查其中与本文主题直接相关的测试资产packages/front-end/test/footprintParity.test.ts——前端环境足迹计算与 shared 实现的 parity 校验packages/back-end/test/api/permission-prediction-parity.test.ts——控制端权限预测与端点 oracle 的 parity 校验packages/front-end/ui/sizes.ts——设计系统尺寸词汇表与radixSize映射的类型定义packages/shared/src/permissions/controlAuthority.ts——控制端可展示内容授权预测的共享纯函数。小结packages/front-end/AGENTS.md 虽然篇幅不长但它把 GrowthBook 前端开发中最容易漂移的四类问题都钉死了组件选型/ui/优先、尺寸走 T-shirt 梯度、Bootstrap 只减不增、数据获取SWR 的useApiapiCall 手动缓存刷新、权限控制预测与端点共享同一规则源用两套 parity 测试和独立夹具强制对齐足迹与原子按 flag-family 授权模型的四个名词精确选用、文案大小写Heading Title Case / 其余 sentence case / 命名资源恒 Title Case。再加上由next dev自动维护的 Next.js 规则块这份规范本质上是一份让 Agent 和人类在同一套规则下工作的契约——它约束的不是某一行代码而是修改代码前必须先读的指南、写权限检查时必须过的测试。赞分享后端前端数据分析数据可视化【免费下载链接】growthbookOpen Source Feature Flags, Experimentation, and Product Analytics项目地址https://gitcode.com/gh_mirrors/gr/growthbook点击查看免费下载相关推荐GrowthBook 后端开发完全指南权限、商业特性、数据模型层、REST API 与示例数据GrowthBook 后端开发完全指南权限、商业特性、数据模型层、REST API 与示例数据 本文基于 GrowthBook 开源仓库的后端开发者文档 pa后端前端数据分析数据可视化ECC Web Patterns 前端模式指南组件组合、状态管理与数据获取的实战规范ECC Web Patterns 前端模式指南组件组合、状态管理与数据获取的实战规范 本指南基于 ECC 规则库中的 docs/ja JP/rules/web人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具Sim 前端数据层规范React Query 模式、Query Key 工厂与 CI 强制校验实践Sim 前端数据层规范React Query 模式、Query Key 工厂与 CI 强制校验实践 在 Sim一个用于构建、部署和监控 AI 智能体与工作流人工智能AI AgentAgent 工作流工作流自动化AI 应用后端前端桌面应用CLI上一篇NCM文件解密工具ncmdumpGUI完整使用指南下一篇解锁PhotoMovie核心功能滤镜、转场与音乐同步完全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考