vitepress-template

Appearance

开发规范 ​

**本文引用的文件** - [[README.md]](../file/readme.md) - [[ui-web/package.json]](../file/ui-web/package.json) - [[ui-web/eslint.config.mjs]](../file/ui-web/eslint.config.mjs) - [[ui-web/tsconfig.json]](../file/ui-web/tsconfig.json) - [[bi-common/apitypes/response.go]](../file/bi-common/apitypes/response.go) - [[bi-common/apitypes/error.go]](../file/bi-common/apitypes/error.go) - [[bi-common/apitypes/request.go]](../file/bi-common/apitypes/request.go) - [[bi-common/apitypes/page.go]](../file/bi-common/apitypes/page.go) - [[bi-common/registry/nacos/nacos-default.yaml]](../file/bi-common/registry/nacos/nacos-default.yaml) - [[bi-common/cache/redisx/redisx-default.yaml]](../file/bi-common/cache/redisx/redisx-default.yaml) - [[AGENTS.md]](../file/agents.md)

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言 ​

本开发规范旨在统一 BI 分析平台的开发行为，确保前后端一致的代码风格、可靠的 API 响应与错误模型、可维护的配置与部署流程，并建立可执行的质量与安全标准。规范内容覆盖 Git 提交规范、代码规范（TypeScript 严格模式、ESLint、Prettier）、组件化开发原则、响应式设计要求、代码审查标准与质量保证流程、最佳实践与约定俗成的开发模式。

项目结构 ​

  • 项目采用多模块微服务架构，前端以 Next.js 16 App Router 为核心，后端以 Golang Kratos 框架为主，结合 Kafka、StarRocks、APISIX 等基础设施。
  • 前端包含多个独立应用：租户控制台、运营后台、技术站点、顶部导航、浏览器扩展等；后端包含分析服务、基础数据服务、定时任务、消息通知、系统管理、租户管理等多个子服务。
  • 项目提供统一的公共库（bi-common）封装 API 统一响应、错误模型、分页与请求参数、缓存与注册中心配置等。

章节来源

核心组件 ​

  • 统一响应与错误模型：后端通过统一响应结构与业务错误码，结合 Kratos 错误与 Metadata，实现清晰的错误传递与状态映射。
  • 分页与请求参数：提供通用分页、排序、时间范围等请求模型，确保 API 设计一致性。
  • 配置中心与缓存：Nacos 默认配置与 Redis 连接池配置，便于动态配置与缓存策略落地。
  • 前端工程化：Next.js + TypeScript 严格模式 + ESLint 核心规则，确保类型安全与代码质量。

章节来源

架构总览 ​

  • 前端：Next.js 16 App Router + TypeScript 严格模式 + ESLint 核心规则，组件化开发，响应式设计。
  • 后端：Kratos + gRPC/Protobuf + Kafka + StarRocks + APISIX 网关。
  • 公共库：统一响应/错误/分页/请求参数、Nacos 配置、Redis 缓存、日志与可观测性等。

章节来源

详细组件分析 ​

Git 提交规范 ​

  • 类型包括：feat（新功能）、fix（修复 bug）、chore（构建工具或辅助工具变动）、docs（文档更新）、style（代码格式调整）、refactor（重构）、test（测试相关）。
  • 建议遵循“类型: 内容”的简洁格式，配合变更描述与影响范围，便于自动化工具解析与版本发布。

章节来源

代码规范（TypeScript 严格模式、ESLint、Prettier） ​

  • TypeScript 严格模式：开启 strict、noEmit、isolatedModules 等选项，确保类型安全与构建稳定性。
  • ESLint：基于 Next.js 官方规则集，统一核心 Web Vitals 与 TypeScript 规则，忽略构建产物与临时输出目录。
  • Prettier：与 ESLint 协同，避免格式争议，统一代码风格。

章节来源

组件化开发原则 ​

  • 前端组件应职责单一、可复用性强，遵循“以页面/功能域”划分目录，使用类型约束与受控属性，减少副作用。
  • 状态管理采用 Zustand，保持全局状态最小化与可追踪。
  • 图表可视化采用 ECharts，按需引入模块，避免打包体积膨胀。

章节来源

响应式设计要求 ​

  • 使用 Tailwind CSS 实现响应式布局，移动端优先，确保在不同设备上的可读性与交互体验。
  • 仪表板与表格组件需支持自适应宽度、折叠与排序，提升大数据场景下的浏览效率。

章节来源

API 统一响应与错误模型 ​

  • 统一响应结构包含 code、message、data 字段；成功时 code 为 0，错误时返回业务错误码与消息。
  • 业务错误码采用 XXYYZZZ 格式，XX 部分映射 HTTP 状态码，便于前端统一处理与网关返回策略。
  • 支持从 Kratos 错误中提取业务错误码与消息，兼容 Metadata 存储。

图表来源

章节来源

分页与请求参数模型 ​

  • 分页请求包含页码与每页条数，提供校验与偏移量/限制数量计算。
  • 排序请求包含排序字段与方向，默认降序；时间范围请求包含起止时间并进行有效性校验。
  • 通用 ID/IDs 请求用于单条或多条资源的批量操作。

图表来源

章节来源

配置中心与缓存 ​

  • Nacos 默认配置：包含服务端、客户端、配置、认证与高级选项，支持本地调试与多环境切换。
  • Redis 连接池配置：支持单机、哨兵与集群模式，提供连接池大小、超时与 TLS 等参数，便于性能与稳定性调优。

章节来源

代码审查标准与质量保证流程 ​

  • 审查维度：安全性（注入、鉴权、输入验证）、性能（N+1、缓存、索引）、错误处理（异常捕获、错误消息）、代码质量（函数复杂度、命名、魔法数）、测试质量（真实断言、覆盖率）。
  • 流程要点：逐条验收准则验证、任务完成审计、深度代码质量检查、非功能性需求评估（安全、性能、可靠性、可维护性）、技术债识别与主动重构、符合性检查与验收标准验证。

章节来源

依赖关系分析 ​

  • 前端依赖 Next.js 16、TypeScript、Tailwind CSS、ECharts、Zustand 等，通过 package.json 管理脚本与依赖。
  • 后端依赖 Kratos、gRPC、Kafka、StarRocks、APISIX 等，通过 go.mod 管理模块与版本。
  • 公共库 bi-common 为各服务提供统一的响应、错误、分页与配置能力，降低重复实现与耦合度。

章节来源

性能考量 ​

  • 前端：合理拆分路由与组件，使用 Suspense 与懒加载；Tailwind 原子类减少样式体积；ECharts 按需引入模块。
  • 后端：利用 Kafka 异步解耦，StarRocks 优化查询与分区策略，必要时引入缓存与限流；统一响应与错误模型降低前端适配成本。
  • 配置：Nacos 动态配置与 Redis 连接池参数按环境调优，确保高并发下的稳定性。

章节来源

故障排查指南 ​

  • 统一错误模型：前端通过业务错误码与消息快速定位问题；后端通过 Metadata 透传业务码，便于跨服务追踪。
  • 配置中心：确认 Nacos 地址、命名空间、分组与 DataID 是否正确，避免配置缺失导致的功能异常。
  • 缓存：检查 Redis 连接参数、连接池大小与超时设置，关注 TLS 与认证配置。
  • 日志与可观测性：结合日志与指标监控定位性能瓶颈与错误根因。

章节来源

结论 ​

本规范以“统一响应与错误模型、严格的前端工程化、可维护的后端模块化、完善的代码审查与质量保证”为核心，辅以配置中心与缓存的最佳实践，帮助团队在快速迭代的同时保持高质量与高效率。建议在日常开发中严格执行上述规范，并持续优化流程与工具链。

附录 ​

  • 前端开发与构建脚本：参见 ui-web/package.json 的 scripts 字段。
  • 技术栈与模块概览：参见 README.md 的技术架构与目录结构。

章节来源