# 开发指南

CODIA 致力于打造面向编程教育的智能在线教育系统。本文档介绍 CODIA 项目的开发中涉及的技术、设计、实现细节等。

# 什么是 CODIA

CODIA 的核心目标是打造面向编程教育的智能在线教育系统。这包括如下三个方面:

  • 针对编程学习者和教育者:教、学两端并重
  • 面向编程教育:重新定义编程教育中学习、练习、评估等教育过程
  • 实现智能系统:探索诊断、推荐、分析报告等智能应用

与其他在线学习、在线编程等相关网站对比,本平台的独特之处在于(TODO: 待补充整理):

  • 沉浸式的在线编程:相比绝大多数在线编程平台,CODIA 致力于提供优质的在线沉浸式编程体验,大幅降低编程练习需要配置环境等的成本。
  • 扁平化的用户体系:每个用户可以作为学生学习和练习,也可以作为老师分享知识、设计练习、组织比赛等,这为平台增加了很强的参与感和灵活性。
  • 大数据支撑的智能分析和推荐

# 整体架构

下面是整个项目的架构图: 架构图

其中有几个方面需要解释:

  • 项目整体可分为前端、后端以及外部模块。前端与后端(图上核心平台)之间主要通过 GraphQL 接口沟通和传递数据。后端与外部模块之间则通过消息队列沟通和传递数据。
  • 项目各模块作为微服务各自部署和运行,因此可以针对不同的需要使用不同的语言和工具编写。但各模块需要提供风格一致的接口以及详细的接口文档。
  • 图中涉及多项持久化存储,这些存储之间可能存在冗余,但这是因为它们分别有不同的定位。具体而言,结构化数据库中存储的是业务状态,主要面向业务逻辑相关接口;对象存储(阿里云 OSS)中存储的是较大的存储对象(数据库中就可以中只存对象的 key,以减小存储成本);Redis 中存储着自定义结构的数据、缓存数据以及临时数据,主要服务投递模块、评测模块、社区模块(图上未包含)等;ElasticSearch 中则存储着文档、日志等可用于检索和分析的数据,主要面向搜索、分析、推荐等模块。

# 文档指南

# 文档介绍

随着 CODIA 项目逐渐庞大和复杂化,文档的作用也日渐重要。良好的文档不仅是新成员了解项目开发的最重要的入口,也是现有成员对于开发工作的汇总、整理和参考,对于降低学习成本、思维成本,应对项目开发的复杂性,促进项目持续发展而言十分重要。

针对这些需求,本文档主要分为三个部分。第一部分是开发指南,主要讲解项目各重要模块开发的基本流程、基本模式、基本原则等。这部分将按照项目结构,围绕项目开发中的各项主题(如 UI 组件编写、业务接口设计、测试编写、部署配置等),提供相应的入门路径以及最佳开发实践参考。

第二部分是业务指南。以第一部分介绍的工程技术作为工具,开发人员真正的目标是完成实际业务,最终形成一个高质量的产品。因此,第二部分主要定义平台作为一项产品的目标、定位、设计等,包括产品目标、产品受众、产品所需业务、各项子业务目标、流程、逻辑等的设计参考。

第三部分是 API 参考。这部分将提供项目中每个编程接口的设计和使用参考。很多软件包/项目的 API 文档是从源代码自动生成的。而在该项目中我们将人工维护整个项目的 API 参考文档。这样做有如下几项原因:

  • 本项目由多个子项目组成,分散多处的文档将增加查阅和交叉引用的难度,而统一的文档难以针对多个项目、多种语言统一使用自动文档生成工具生成(即使可以生成,文档编写成本也会大幅增加)。
  • API 参考中需要列出最重要、最常参考,有时也是最难理解的编程接口,这样的接口需要详实的文档参考,往往也需要例子的辅助,在源代码中嵌入这些文档反而会影响源码的观感。
  • 源码中仍然可以(也需要)增加内嵌文档,但这些文档应当更加关注实现。统一的 API 参考文档则关注接口的设计和使用规范,应当脱离实现细节。

开发人员应当以这些文档为基础进行开发工作,同时将开发的工作反馈回文档中。开发人员实现的每项功能至少应当包含一份 API 参考,根据实现的内容,还应当包含相应的业务介绍或开发指南。

# 文档编写

文档编写大致遵循 Vue 文档编写指南 中的原则和规范,这些原则和规范需要每个开发人员阅读(因为每个开发人员也同时是文档编写的参与者)。其中较为重要的几项列举如下:

  • 除非有充分的文档记录,否则功能不存在;
  • 从读者/用户的角度思考;
  • 充分考虑和尊重读者的认知能力及认知规律,多使用短句子、例子等,引导读者的好奇心;
  • 首先描述问题、背景、动机等,然后再描述解决方案。

除此之外,其他文档编写指南中所列举的条目也值得阅读。

# 编辑本文档

本文档对应仓库地址在这里。每次提交后,新的文档会被自动部署到这里,因此可以直接使用 GitLab 提供的 Web IDE 编辑。然而更加推荐的方式是在本地编辑和预览结果。首先克隆项目:

git clone git@git.bdaa.pro:code-platform/codia-dev-docs.git
cd codia-dev-docs
1
2

或拉取最新版本:

cd path/to/codia-dev-docs
git pull
1
2

然后可以通过 npm 运行:

npm run dev
1

一份实时更新的文档即能够在默认地址(http://localhost:8080/)访问。

Last Updated: 2020/10/2 上午3:49:27