在开源社区蓬勃发展的浪潮中，OSS-Compass 构建了基于指标模型的开源项目评估体系，历经两年的打磨与沉淀，其功能不断完善，社区日益壮大。对于有志于在 OSS-Compass 社区发光发热的开源开发者而言，深入理解项目前端技术架构是开启贡献大门的关键钥匙之一。
在本文中，我们将深入探讨 OSS-Compass 平台的前端主仓项目架构和开发环境，涵盖其技术栈、文件结构、路由系统、API 交互、开发环境搭建等关键部分，帮助读者理解其背后的设计思路和实现细节。而在后续的系列文章中，我们还将深挖项目分类仓管理技巧，探索文档仓构建与优化方法，钻研 API 交互细节以提升数据交互效能。期望借这一系列内容，为开发者们提供实操经验，助力大家在 OSS - Compass 社区稳步踏出贡献步伐 。
1. 架构模式
OSS-Compass 前端采用了基于 React 的单页应用（SPA）架构模式，结合 Next.js 实现了服务端渲染（SSR）。选择 React 作为构建用户界面的基础，是因其虚拟 DOM 机制能高效地处理界面更新，以组件化开发模式将复杂页面拆分成一个个独立、可复用的模块，极大提升了代码的维护性与可扩展性。在 OSS-Compass 里，无论是基础的按钮、搜索框组件，还是像分析页模型数据图表这类复杂页面组件，都被精心封装，每个组件专注自身功能逻辑，降低了代码耦合度。而 Next.js 的引入为项目带来 SSR 与 SSG 特性，这有助于提高页面性能并改善搜索引擎优化（SEO），并极大提升了用户操作响应速度与体验。
2. 核心技术栈
| 技术分类 | 技术选型 | 选型理由与关键实践 |
|---|---|---|
| 核心框架 | React + TS + Next.js | 基于组件化开发模式，通过 TS 实现接口类型约束，Next.js 实现 SSR。 |
| 样式方案 | Tailwind CSS | 实用优先的 CSS 框架，用于快速构建样式。 |
| 组件库 | Ant Design | 开源 UI 设计语言和组件库，不仅具有美观的设计，而且经过了大量的实践验证，具有良好的稳定性和易用性。 |
| 可视化 | ECharts | 广受好评的图表可视化开源框架，社区在 OSS-Compass 平台度量评分高，优于其他竞品 。 |
| 状态管理 | Context API | 在组件之间共享状态的简单而轻量的方法。 |
| 工程化 | ESLint + Prettier + Husky | 用于识别和报告 JavaScript 代码中的问题，提交前自动格式化。 |
| 国际化 | i18next | 多语言文件按命名空间拆分（如：i18n/{lang}/common.json），支持 SSR 动态加载。 |
3. 文件结构
web/src/
├── common/ // 可复用组件、常用工具函数、公用hooks
├── pages/ // 文件系统路由
├── modules/ // 路由对应的模块化页面、如分析页、Lab页、协作页等
└── styles/ // 样式文件（Tailwind 和自定义样式）
web/i18n/
└── {lang} // 国际化配置
graphql/
└── src/gql/ // Graphql API 请求
4. 路由系统
Next.js 使用文件系统作为路由的基础，每个在 pages 文件夹中的文件都会自动对应一个路由。这种方式使得路由的管理变得简单且直观。例如：
pages/
├── analyze/ // 模型分析页面路由
│ └──[slugs].tsx // 模型分析页动态路由 slugs 为项目id
├── collaboration/ // 协作页路由
└── lab/ // Lab页路由
Next.js 支持动态路由，使得开发者可以根据 URL 参数动态渲染页面。通过使用方括号（[]）语法，可以轻松实现动态路由。例如，[slugs].tsx 文件可以用于展示项目的模型评估信息。
5. API 交互
OSS-Compass 采用 GraphQL 进行前后端数据交互 。与传统的 RESTful API 相比，GraphQL 允许前端精确地指定需要获取的数据，后端只会返回前端请求的数据，避免了数据的过度获取或不足获取。例如，在获取用户的登录信息时，前端可以通过 GraphQL 查询只请求用户的名称、头像等必要字段，而无需像 RESTful API 那样可能获取到大量不需要的额外数据。这样不仅减少了数据传输量，提高了应用性能，还使得数据请求更加灵活和可定制。
6. 开发流程与规范
(1) 开发环境搭建
- 安装依赖：首先，需要克隆 OSS-Compass 的前端项目仓库到本地。进入项目目录后，使用 yarn 安装项目所需的依赖包。项目的 package.json 文件中已经列出了所有依赖，包括 React、Next.js、Tailwind CSS 等相关库。
- 配置环境变量：配置后端 API 的地址环境变量，在项目 web 目录下.env.local 文件，并在其中添加后端 API 的地址来进行配置。
- 启动开发服务器：安装完依赖并配置好环境变量后，使用 yarn dev 命令启动开发服务器。此时，浏览器会自动打开项目的本地开发地址，开发者可以在浏览器中实时预览和调试代码。
(2) 代码规范 ESLint 、Prettier、Husky
OSS-Compass 项目使用 ESLint 进行代码质量检查，使用 Prettier 进行代码格式化，使用 Husky 在提交前执行 ESLint 脚本。ESLint 能够检测代码中的语法错误、潜在的逻辑问题以及不符合代码规范的地方，而 Prettier 则可以自动格式化代码，使其风格统一，相关配置文件可在 web 根目录中查看。在开发过程中，建议开发者在编辑器中安装 ESLint 和 Prettier 插件，这样在保存文件时，编辑器会自动根据配置对代码进行检查和格式化。
7. 总结
通过深入了解 OSS-Compass 前端技术栈，掌握开发流程，开发者可前往 OSS-Compass 社区仓库 查看源码、issues，参与社区讨论，寻找自己感兴趣且有能力解决的问题并尝试贡献代码。 希望本文能够成为你开启 OSS-Compass 开源贡献之旅的指南，让我们共同努力，推动 OSS-Compass 在开源评估领域不断前行，为全球用户带来更优质的服务。