代码规范

**本文档引用的文件** - [[bi-analysis/go.mod]](../file/bi-analysis/go.mod) - [[bi-common/go.mod]](../file/bi-common/go.mod) - [[bi-proto/Makefile]](../file/bi-proto/makefile) - [[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/response.go]](../file/bi-common/apitypes/response.go) - [[bi-common/observability/logger/logger.go]](../file/bi-common/observability/logger/logger.go) - [[bi-common/auth/middleware.go]](../file/bi-common/auth/middleware.go) - [[bi-common/mq/kafkax/consumer.go]](../file/bi-common/mq/kafkax/consumer.go) - [[bi-common/database/gormx/config.go]](../file/bi-common/database/gormx/config.go) - [[bi-common/registry/nacos/config.go]](../file/bi-common/registry/nacos/config.go) - [[bi-common/cache/redisx/config.go]](../file/bi-common/cache/redisx/config.go) - [[bi-common/fx/fx.go]](../file/bi-common/fx/fx.go) - [[ui-web/eslint.config.mjs]](../file/ui-web/eslint.config.mjs) - [[ui-web/package.json]](../file/ui-web/package.json) - [[bi-chat/requirements.txt]](../file/bi-chat/requirements.txt)

目录

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

引言

本指南面向BI分析平台的多语言工程，统一Go、TypeScript/Next.js、Python（AgentScope）与Protobuf相关开发规范，覆盖命名约定、包结构、错误处理、并发安全、注释与日志、错误处理模式、代码审查清单与质量门禁、架构约束与设计模式、以及自动化格式化与静态分析工具配置。目标是提升团队代码风格一致性与可维护性。

项目结构

• Go后端采用模块化工作区，核心公共能力位于bi-common，各业务服务（如bi-analysis、bi-basic、bi-api-xxx）复用公共模块与Protobuf定义。
• TypeScript前端基于Next.js，使用ESLint与TypeScript配置。
• Python侧使用AgentScope框架，配合FastAPI与Pydantic等生态。
• Protobuf定义集中于bi-proto，通过Makefile统一生成gRPC、HTTP、OpenAPI与校验代码。

图示来源

• [bi-analysis/go.mod]
• [bi-common/go.mod]
• [bi-proto/Makefile]

章节来源

• [bi-analysis/go.mod]
• [bi-common/go.mod]
• [bi-proto/Makefile]

核心组件

• 统一错误模型与响应格式：通过apitypes提供业务错误封装、Kratos错误映射与统一响应结构。
• 观测性日志：支持本地与阿里云日志聚合、多输出与级别过滤。
• 鉴权中间件：JWT认证与RBAC权限控制，区分管理端与客户端路径。
• 数据访问：GORM配置（MySQL/StarRocks）、TLS与连接池优化。
• 消息队列：Kafka消费者抽象，优雅关闭与DLQ写入。
• 注册中心：Nacos配置加载与校验。
• 缓存：Redis多模式（单机/哨兵/集群）配置与超时、TLS。
• 通用扩展：fx选项模式（重试、超时）。

章节来源

• [bi-common/apitypes/error.go]
• [bi-common/apitypes/response.go]
• [bi-common/observability/logger/logger.go]
• [bi-common/auth/middleware.go]
• [bi-common/database/gormx/config.go]
• [bi-common/mq/kafkax/consumer.go]
• [bi-common/registry/nacos/config.go]
• [bi-common/cache/redisx/config.go]
• [bi-common/fx/fx.go]

架构总览

• 服务间通信：gRPC + HTTP网关，结合Kratos中间件链路（鉴权、日志、指标）。
• 数据层：GORM（MySQL/StarRocks），连接池与慢查询日志；Redis缓存；Kafka消息。
• 配置与注册：Nacos配置中心与服务发现。
• 前端：Next.js应用通过HTTP调用后端API。
• Python智能体：AgentScope + FastAPI提供对话与分析能力。

图示来源

• [bi-common/auth/middleware.go]
• [bi-common/observability/logger/logger.go]
• [bi-common/database/gormx/config.go]
• [bi-common/cache/redisx/config.go]
• [bi-common/mq/kafkax/consumer.go]
• [bi-common/registry/nacos/config.go]

详细组件分析

Go语言编码规范

• 命名约定
  • 包名小写、简短、语义明确；避免复数与缩写。
  • 类型与接口首字母大写；方法与字段遵循驼峰；常量使用大写与下划线分隔。
  • 测试文件以“_test.go”结尾；基准测试以“Benchmark”开头。
• 包结构
  • 采用“internal/”隔离内部实现；对外公开API置于顶级包。
  • 业务域划分清晰：biz（业务逻辑）、data（数据访问）、service（服务编排）、server（HTTP/gRPC入口）。
• 错误处理
  • 使用apitypes.NewBizError封装业务错误，携带业务码与消息；通过GetBizCode提取业务码。
  • 对外HTTP统一返回200，业务码在响应体中体现。
• 并发安全
  • 使用互斥锁保护共享状态；避免在goroutine中持有长锁。
  • 使用context传递取消信号与超时；在关键路径设置超时。
• 注释与文档
  • 包注释与导出类型/函数注释完整；复杂算法提供流程说明。
• 日志
  • 使用kratos log，支持本地与阿里云日志聚合；按级别过滤；避免敏感信息输出。
• 配置与环境
  • 使用YAML配置并通过DefaultConfig/Merge组合；支持环境变量覆盖。
• 依赖管理
  • 使用go.mod与替换规则指向本地bi-common与bi-proto；定期执行go mod tidy。

章节来源

• [bi-common/apitypes/error.go]
• [bi-common/apitypes/response.go]
• [bi-common/observability/logger/logger.go]
• [bi-common/database/gormx/config.go]
• [bi-common/cache/redisx/config.go]
• [bi-common/mq/kafkax/consumer.go]
• [bi-common/registry/nacos/config.go]

TypeScript/JavaScript规范（Next.js）

• ESLint配置
  • 使用eslint.config.mjs集成Next.js核心Web Vitals与TypeScript规则；忽略.next/out/build等产物目录。
• Prettier与格式化
  • 在项目中引入prettier与editor配置，统一缩进、引号、尾逗号等；与ESLint规则协同。
• React组件规范
  • 函数组件优先；使用Hooks组织状态与副作用；组件文件按功能拆分至src/components子目录。
  • Props使用TypeScript接口定义；避免内联样式，使用CSS Modules或Tailwind。
• 路由与页面
  • 使用App Router与动态路由；页面组件按目录结构组织；静态资源放置public。
• 构建与脚本
  • package.json中定义开发、构建、预览与lint脚本；确保CI可直接运行。

章节来源

• [ui-web/eslint.config.mjs]
• [ui-web/package.json]

Python代码规范（AgentScope框架）

• 依赖与版本
  • 使用requirements.txt统一依赖；AgentScope版本固定，确保智能体行为一致性。
• 项目结构
  • FastAPI应用入口与路由分离；Pydantic模型定义请求/响应；日志使用loguru。
• 智能体与会话
  • 使用AgentScope会话上下文；避免在主线程阻塞；异步任务使用async/await。
• 数据访问
  • SQLAlchemy/asyncpg连接池配置；SQL拼接使用参数化；注意SQL注入风险。
• 测试
  • pytest与pytest-asyncio；使用httpx发起HTTP请求；覆盖关键分支与异常路径。

章节来源

• [bi-chat/requirements.txt]

Protobuf IDL定义规范与生成约定

• IDL组织
  • 按领域划分目录（analysis/basic/leke/jushuitan/kafka/tenant等）；避免跨域耦合。
• 生成命令
  • 使用bi-proto/Makefile统一安装插件与生成代码；一次make api生成gRPC、HTTP、OpenAPI与校验代码。
• 版本与兼容
  • 语义化版本管理；向后兼容变更；禁止破坏性修改；必要时迁移策略与过渡期。
• OpenAPI导出
  • 生成OpenAPI文档，便于前端与第三方对接；保持schema命名一致。

图示来源

• [bi-proto/Makefile]

章节来源

• [bi-proto/Makefile]

统一错误处理与响应模式

• 业务错误
  • apitypes.NewBizError(code, message)封装业务码与消息；根据XX部分映射HTTP状态码。
• 错误提取
  • GetBizCode/GetBizMessage从Kratos错误中提取业务码与消息。
• 响应结构
  • Response.Code=0表示成功；统一消息字段；Data可选承载数据。

图示来源

• [bi-common/apitypes/error.go]
• [bi-common/apitypes/response.go]

章节来源

• [bi-common/apitypes/error.go]
• [bi-common/apitypes/response.go]

鉴权与中间件（JWT + RBAC）

• 配置项
  • JWTConfig、白名单、黑名单、权限提供者（客户端/管理端）、权限缓存。
• 中间件链
  • JWT认证 + RBAC权限检查；管理端路径通过-mpattern识别。
• 使用建议
  • 为登录等接口配置白名单；对敏感操作开启RBAC；缓存权限结果降低RPC开销。

章节来源

• [bi-common/auth/middleware.go]

观测性日志（本地+阿里云）

• 配置
  • 支持json/text格式；stdout/file/both输出；文件轮转（大小/按日）；级别过滤。
• 多路聚合
  • 本地与阿里云日志同时输出；失败不影响本地日志。
• 最佳实践
  • 生产环境开启文件输出与轮转；避免在日志中输出敏感字段；统一字段命名。

章节来源

• [bi-common/observability/logger/logger.go]

数据库与缓存配置

• GORM（MySQL/StarRocks）
  • 连接池参数、慢查询阈值、TLS配置；StarRocks优化建议（空闲连接数与回收策略）。
• Redis
  • 支持单机/哨兵/集群；连接池、超时、TLS；自定义Dialer。
• Nacos
  • 服务端、客户端、配置中心、鉴权与高级配置；默认值与校验。

章节来源

• [bi-common/database/gormx/config.go]
• [bi-common/cache/redisx/config.go]
• [bi-common/registry/nacos/config.go]

消息队列（Kafka）消费者

• 功能
  • 单分区/消费者组模式；健康检查、拉取/提交offset；优雅关闭与信号监听。
• DLQ
  • 失败消息写入死信队列；支持缓存DLQ Writer。
• 最佳实践
  • 批量消费与提交；处理函数幂等；监控lag与错误日志。

图示来源

• [bi-common/mq/kafkax/consumer.go]
• [bi-common/mq/kafkax/consumer.go]

章节来源

• [bi-common/mq/kafkax/consumer.go]

通用扩展（fx选项模式）

• 重试与超时
  • 通过WithRetry/WithTimeout设置默认重试次数与超时；在调用方按需覆盖。

章节来源

• [bi-common/fx/fx.go]

依赖分析

• Go模块
  • bi-analysis依赖bi-common与bi-proto；bi-common依赖Kratos、GORM、Redis、Kafka、Nacos等生态组件。
• 生成依赖
  • bi-proto通过Makefile安装protoc-gen-go、protoc-gen-go-grpc、protoc-gen-go-http、protoc-gen-openapi、protoc-gen-validate。

图示来源

• [bi-analysis/go.mod]
• [bi-common/go.mod]
• [bi-proto/Makefile]

章节来源

• [bi-analysis/go.mod]
• [bi-common/go.mod]
• [bi-proto/Makefile]

性能考虑

• 数据库
  • StarRocks连接池优化：空闲连接数与回收策略；慢查询阈值与日志级别。
• 缓存
  • Redis连接池大小与超时；按延迟/随机路由；TLS与协议版本。
• 消息队列
  • 批量大小与提交间隔；消费者组与分区分配；优雅关闭避免消息丢失。
• 日志
  • 文件轮转与压缩；生产环境避免过多debug日志。
• 中间件
  • 鉴权与权限检查尽量缓存；减少RPC调用频次。

故障排查指南

• 错误码提取
  • 使用GetBizCode/GetBizMessage快速定位业务错误来源。
• 日志定位
  • 查看本地与阿里云日志；确认级别与输出路径；核对时间戳与trace标识。
• Kafka消费
  • 检查broker连通性、topic/分区配置、offset提交与DLQ写入。
• 配置校验
  • Nacos与数据库/Redis配置的默认值与校验规则；确保DataID/命名空间正确。
• 依赖问题
  • 确认protoc插件安装与版本；执行make api与go mod tidy。

章节来源

• [bi-common/apitypes/error.go]
• [bi-common/observability/logger/logger.go]
• [bi-common/mq/kafkax/consumer.go]
• [bi-common/registry/nacos/config.go]
• [bi-proto/Makefile]

结论

通过统一的错误模型、可观测日志、鉴权中间件、数据库与缓存配置、消息队列抽象以及Protobuf生成流程，BI分析平台实现了跨语言的一致性与可维护性。建议在日常开发中严格遵循本规范，并结合代码审查清单与质量门禁持续改进。

附录

代码审查检查清单

• Go
  • 命名是否符合约定；错误处理是否使用apitypes；日志是否包含敏感信息；并发安全是否到位；配置是否合理。
• TypeScript/JavaScript
  • ESLint与Prettier是否通过；组件结构是否清晰；路由与页面组织是否合理；构建脚本是否可用。
• Python（AgentScope）
  • 依赖版本是否锁定；智能体是否幂等；异步任务是否正确；测试覆盖率是否达标。
• Protobuf
  • IDL是否按领域划分；生成命令是否可重复；OpenAPI是否同步更新。

质量门禁标准

• 代码风格
  • 通过ESLint与Prettier；Go vet与gofmt；Python flake8/Black。
• 测试
  • 单元测试与集成测试通过；覆盖率达标；e2e测试可运行。
• 文档
  • OpenAPI文档与README更新；错误码与响应说明完善。
• 安全
  • 无硬编码密钥；鉴权中间件正确配置；TLS与权限最小化。