项目介绍

• 项目二描述
  • 使用微服务搭建分布式结构的项目。
• 项目二核心内容
  • 业务场景的分析和实现（写清业务的步骤，将文字的步骤变为代码）
  • 使用分布式技术来解决现有问题
  • 重视项目中的规范，对代码内容进行约束
• 项目课程讲法
  • 内容导读实现+思考问题和学员实现
  • 项目中会有组内实战

• 项目学习结果

  • 每天需要同步代码待Gitee，总结项目中重点内容

    学成在线导读

• 学成在线一共是 7个章节，分12天进行讲解。

• 第一章 项目介绍 环境搭建
  • 介绍项目的背景、通过项目的功能架构和技术架构来介绍项目结构。并展示项目的课程主体业务流程内容介绍，搭建项目的初期环境。
• 第二章 内容管理
  • 搭建项目内容管理和系统管理微服务。对内容管理数据模型和主要功能进行强调。对课程基本信息管理、课程计划管理、课程营销管理、课程图片上传等内容，并解决搭建项目全局异常处理器来处理异常信息。
• 第三章 媒资管理
  • 对教学平台的媒体资源进行管理，通过第三方平台来管理媒体信息资源数据，并能在线进行视频的点播来子线观看视频，介绍资源文件的断点和分片上传文件。
• 第四章 课程发布
  • 介绍课程发布的功能，并通过技术层面分析课程发布的功能性需求。在此会通过模板技术来实现课程的详情页并且可以在线预览，从中介绍分布式事务理论，通过RabbitMQ来实现消息的一致性。
• 第五章 课程搜索
  • 介绍互联网项目的特点，并使用索引库来实现课程内容的检索。本内容在课程发布后，会通过数据采集将课程发布后的内容存放到索引库中，达到数据通过索引库来查询出数据。
• 第六章 学生选课
  • 本章节首先来介绍用户认证的需求，并通过UAA服务来实现第三方协议Oauth2的用户认证。分析选课的需求分析和业务流程，完成收费课程的支付功能，并使用分布式任务调度查询支付的结果内容。

• 第七章 课程学习

  • 对课程在线点播进行业务分析，开发课程在线学习对课程计划的查询操作，并通过阿里视频点播方案来实现课程在线播放。、

    学习目标

• 了解项目的背景

  • 熟悉项目的功能架构和技术结构
  • 熟悉项目的具体业务流程
  • 掌握开发工具Swagger
  • 能够搭建环境和使用进行服务的配置
  • 能够使用代码生成器-MP
  • 熟悉开发规范文档

• 需要掌握内容：

  • 项目的功能结构和技术架构
  • 项目的主要业务流程
  • 搭建项目的基础环境
  • 开发工具 Swagger
  • 使用开发其他环境
    • 代码生成器
    • 项目的开发文

      项目背景

      项目处于的环境

• 在线教育近五年来稳步增长

  • 在线教育市场规模未来将持续增长， 一二线城市在线教育市场渐趋成熟， 而三四线城市市场仍处千初步发展阶段。
• 政治环境促进在线教育健康发展
  • 在线教育越发得到重视，相关政策规定的出现，将进一步促进在线教育健康发展。
• 在线教育用户规模再创新高
  • 中国在线教育用户规模逐步上升在2020年达已突破到3.09亿，互联网的普及和发展带来的 ＂互联网十教育” 使得在线教育用户不断奉升。

• 在线教育市场规模将持续增长

  • iiMedia Research （艾媒咨询）数据显示， 在线教育市场规模逐年增长， 2020年达到4538亿元。

    项目基础背景（面试）

• 基于MOOC思想

  • 学成在线借鉴了MOOC（大型开放式网络课程，即MOOC（massive open online courses））的设计思想提供在线教育平台。
  • 可以参考MOOC慕课网
• 提供IT高等教育
  • 提供IT职业课程在线学习的平台，它为即将和已经加入IT领域的技术人才提供在线学习服务。
• 多元学习模式
  • 用户通过学成在线平台进行视频点播在线学习、课程直播在线学习、师生间的针对学习在线沟通。
  • 说的明白一点就是多功能，不在单一学习

• B2B2C业务模式

  • 向企业或个人在线教育平台提供教学服务，老师和学生通过平台完成整个教学和学习的过程.
  • 学成在线本身不卖课，而是提供平台给教育机构或者个体让他们在平台提供教学服务

    总结面试回答：什么是学成在线？

• 学成在线是一个基于MOOC思想，提供了多元化学习方式且主要提供IT方面相关课程，他的业务模式则是采用了B2B2C的业务模式，让教学机构通过台提供教学服务。

对B2B2C业务模式以及B2C业务模式的理解

• B：Business ——商家
• C：Customer ——顾客
• B2C：商家对顾客提供业务服务
• B2B2C：商家对其他商家提供业务服务，让这些商家在对顾客提供业务服务
• 举例说明：
  • 淘宝就是典型的B2B2C业务模式，他没有自营，而是给商家提供了平台，上商家对顾客提供了业务服务
  • 京东则是B2C + B2B2C的业务模式，他有自己的自营店（B2C）；但同时特也为其他商家提供平台是的为顾客进行业务服务（B2B2C）

项目的功能构架（面试）

功能架构介绍

• 从在线教育的火热到如今，在线教育的模式出现多种多样，包括：B2C、C2C、B2B2C等业务模式。学成在线采用B2B2C业务模式，即向企业或个人在线教育平台提供教学服务，老师和学生通过平台完成整个教学和学习的过程，市场上类似的平台有：网易云课堂、腾讯课堂等，学成在线的特点是IT职业课程在线教学。
• 学成在线包括在线教育平台、业务支持系统、基础服务来构建整个功能架构。
• 学成在线功能架构图

功能模块列表

在线教育平台

业务系统支撑

基础服务

项目的技术架构（面试）

项目技术架构分层

• 学成在线采用当前流行的前后端分离架构开发，由以下流程来构成：用户层、CDN内容分发和加速、负载均衡、UI层、微服务层、数据层。

  学成在线技术架构图

  
  技术架构列表

  | 名称 | 功能描述 | | —- | —- | | 用户层
  | 用户层描述了本系统所支持的用户类型包括：pc用户、app用户、h5用户。pc用户通过浏览器访问系统、app用户通过android、ios手机访问系统，H5用户通过h5页面访问系统。
  H5包括Html5、CSS3、ECMA高版本内容；奴蛋蛋局限于Html5 | | CDN
  | CDN全称Content Delivery Network，即内容分发网络，本系统所有静态资源全部通过CDN加速来提高访问速度。系统静态资源包括：html页面、js文件、css文件、image图片、pdf和ppt及doc教学文档、video视频等。 | | 负载均衡
  | 系统的CDN层、UI层、服务层及数据层均设置了负载均衡服务，上图仅在UI层前边标注了负载均衡。 每一层的负载均衡会根据系统的需求来确定负载均衡器的类型，系统支持4层负载均衡+7层负载均衡结合的方式，4层负载均衡是指在网络传输层进行流程转发，根据IP和端口进行转发，7层负载均衡完成HTTP协议负载均衡及反向代理的功能，根据url进行请求转发。 | | UI层
  | UI层描述了系统向pc用户、app用户、h5用户提供的产品界面。根据系统功能模块特点确定了UI层包括如下产品界面类型： 1）面向pc用户的门户系统、学习中心系统、教学管理系统、系统管理中心。 2）面向h5用户的门户系统、学习中心系统。 3）面向app用户的门户系统、学习中心系统。 | | 微服务层
  | 微服务层将系统服务分类三类：业务服务、基础服务、第三方代理服务。 业务服务：主要为学成在线核心业务提供服务，并与数据层进行交互获得数据。 基础服务：主要管理学成在线系统运行所需的配置、日志、任务调度、短信等系统级别的服务。 第三方代理服务：系统接入第三方服务完成业务的对接，例如认证、支付、视频点播/直播、用户认证和授权。 | | 数据层
  | 数据层描述了系统的数据存储的内容类型，关系性数据库：持久化的业务数据使用MySQL。 消息队列：存储系统服务间通信的消息，本身提供消息存取服务，与微服务层的系统服务连接。 索引库：存储课程信息的索引信息，本身提供索引维护及搜索的服务，与微服务层的系统服务连接。 缓存：作为系统的缓存服务，作为微服务的缓存数据便于查询。 文件存储：提供系统静态资源文件的分布式存储服务，文件存储服务器作为CDN服务器的数据来源，CDN上的静态资源将最终在文件存储服务器上保存多份。 |

七层网络模型

http://www.linuxvirtualserver.org/zh/lvs1.html

●业务流程举例：

• 用户可以通过pc、手机等客户端访问系统进行在线学习。
• 系统应用CDN技术，对一些图片、CSS、视频等资源从CDN调度访问。
• 所有的请求全部经过负载均衡器。
• 对于PC、H5等客户端请求，首先请求UI层，渲染用户界面。
• 客户端UI请求服务层获取进行具体的业务操作。

• 服务层将数据持久化到数据库。

  项目技术栈

• 学成在线按照技术分层的基础上，需要对主要层次使用具体的技术作说明。下面是学成在线技术栈结构图

  技术栈（技术结构图）

  
  技术栈列表

  | 技术层名称 | 技术栈 | | —- | —- | | 视图层 | 页面的构建：微信等使用H5技术、PC使用前端技术Vue/React、移动端使用App(安卓/ios) | | 微服务接入控制层 | GateWay、Eureka、Ribbon、Sentinel、Feign | | 微服务层微服务层 | Spring Boot 、Druid、Lombok、MapStruct、Mybatis plus、sharding-jdbc、swagger、XXL-job、Freemark | | 数据访问层 | 使用Spring Data 、Mybatis 等 |

项目主体业务流程(面试)

• 在学成在线整个学习周期中，课程里会对主要核心的业务进行实现，主要包含三方面的业务流程：

  • 第三方教学机构
  • 学成在线管理平台人员
  • 学员

    教学机构业务主体流程

    教学机构业务主体流程示意图

    
    上图中的简要流程：

• 教学机构先入住到学成在线平台中

• 教学机构人员在学成进行登
• 在教学管理中心可以管理课程信息
• 课程管理是会使用阿里云和七牛云服务
• 教学机构在课程没有问题的情况下将课程进行提交审核

• 课程审核通过后，教学机构可以发布课程。

  平台机构业务主体流程

  平台机构业务主体流程示意图

  
  上图中的简要流程：

• 平台机构在学成进行登录

• 在教学管理中心管理教学机构课程内容
• 课程中需要从外部服务中获得课程内容数据，并进行预览

• 预览课程内容后，需要对课程进行审核

  学员业务主体流程

  学员业务主体流程示意图

  

• 上图中的简要流程：

  • 学员在学成的门户注册后进行登录
  • 在门户搜索需要学习的课程内容
  • 找到对应课程后，需要对课程进行 下单购买
  • 在学习中心查看自己课程，并进行学习 视频播放时会使用到第三方的服务。

• 上图信息如下：

  • 使用人群：
    • 第三方教学机构
    • 学成在线管理平台人员
    • 学员
  • 主要业务操作：
    • 由第三方的教学机构在学成在线系统中录入教学数据
      • 在录入数据前，需要进行登录认证，然后录入教学数据包括直播和点播。
    • 由学成在线管理平台人员对学成在线系统中第三方教学机构的课程内容进行审核操作
      • 第三方的教学内容，需要平台人员进行审核。审核通过，学员才可以对其进行学习。
    • 学员需要登录到学成在线平台，添加需要学习的课程进行学习
      • 对于收费的课程需要进行下单购买，才可以进行学习
  • 主业务和外部服务交互：
    • 学成在线系统中对于用户的认证将使用第三方认证系统UAA来完成
      • 系统中的三类用户都需要通过UAA系统来获得认证和授权
    • 学成在线中的教学资料会使用第三方的分布式系统来保存
      • 对于视频点播/直播会使用阿里元服务
      • 对于文件会使用七牛云进行存储

        项目环境搭建

        开发环境配置

• 笔记https://www.yuque.com/docs/share/07f11a17-4e39-4e16-a506-c28cceaccf74?# 《开发工具环境配置》

  项目基础工程搭建

  项目工程结构关系

• 学成在线使用 Maven 来进行项目的管理和构建，使用 Maven 的一些特性来对项目进行结构化的划分。整个项目分为三大类工程：父工程、基础工程 和 业务功能微服务工程

  项目关系结构图

  

• 每一种类的工程都有不同的作用，下面是对其功能进行说明：

  • 父工程
    • 继承SpringBoot父类工程 ,构建微服务工程
    • 对依赖的包进行管理
    • 对依赖包的版本进行管理
    • 本身为Pom工程，对子工程进行聚合管理
  • 基础工程
    • 继承父类工程，将相关被管理的依赖坐标引入
    • 通用组件工程（xc-common）
      • 对微服务工程公共内容进行管理
    • 接口工程（xc-api）
      • 对各个模块的微服务接口进行统一管理
      • 对接口交互数据DTO进行管理
  • 业务功能微服务工程
    • 对学成在线业务模块功能进行实现（每个微服务只实现单个业务模块）

      基础工程的导入

• 在今天下发资料中，有父工程和基础工程，我们直接将其导入到 IDEA 中即可。其中有很多的配置，后期的课程中接触到了在详细的阐述。

• 下面我们开始将基础工程导入 IDEA中。

创建一个空工程后，将今天下发资料中 ‘\资料\基础工程\xc-parent.7z ’ 解压到空的工程中，然后以模块的方式发开就可以。

• 将下发资料的基础工程解（xc-parent）压到本地（路径不要有特殊字符和中文名称）

PS：对于基础工程和项目构建在实际项目里，一般都是有架构师或项目主程这两位角色来创建。其他的开发人员都是将基础工程从代码托管平台下载下来，在此基础上进行开发，并非由程序员来搭建项目。所以，我们的基础工程在设计好后，直接导入进行开发，希望大家知晓。

操作步骤：

• 在本地创建目录，目录路径不能有中文和特殊字符

• 在该目录下创建出两个目录

• 将今日资料基础工程项目拷贝到back_code目录中

• 使用idea创建工程

• 导入xc-parent工程

项目数据库环境

学成在线数据库环境介

• 学成在线课程的基础数据存储在 Mysql 中，数据将以分库分表的方式进行数据操作，不同的业务操作不同的数据库，下面是对分库分表的具体划分。
• 分库数据划分
  

• 后面的课程中设计到的业务，就会来搭建出对应的数据库，等讲到哪块业务再导入对应的数据库。

  项目开发简化工具

• 对于现如今的项目开发业务功能，都会使用一些工具简化实际的工作量。学成在线对其也使用了简化工具在项目中，简化内容主要有后端的代码简化、开发接口文档自动生成，下面我们分别进行说明。

  Swagger 后端 API 文档工具介绍

• 随着软件架构的演变，现如今的开发模式也有不小的变动。微服务的出现，使得开发模式变为前后端分离式开发。后端的微服务端开发接口地址，需要开发人员开发阶段编写接口文档。

• 接口文档就是对后端开发的接口地址的列表和每个接口地址的描述，之前的接口文档，一般是开发人员通过编写文档的形式来体现。但手写接口文档费时费力，能不能通过程序自动生成呢？对于现在来说，当然是可以的，它就是后端 API 文档生成工具 ：Swagger。
• Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger UI生成的界面比Javadoc生成的界面美观 ,可以实时同步API文档(代码修改后，文档同步修改) ,对SpringMVC工程支持友好。
  swagger 官方网站：https://swagger.io/
• 对于 Spring Boot 对 Swagger 的集成，自然是很简单。国人对此制作出 Spring Boot 对 Swagger 启动器。更加便捷在 Spring Boot 工程中使用并配置。
  spring-boot-starter-swagger启动器

• https://github.com/SpringForAll/spring-boot-starter-swagger

  Swagger 使用方式

• 创建 Spring Boot 工程 （省略）

  • 在 IDEA 中开发环境下创建测试模块 test-swagger 。

• 在 pom 文件中添加 Swagger 的 Spring Boot 启动器

  <!-- 继承 Spring Boot 父工程 -->
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.3.2.RELEASE</version>
  </parent>
  <!--添加 spring boot web 依赖-->
  <dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- swagger对springboot的集成 -->
    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.9.0.RELEASE</version>
    </dependency>
    <!-- lombok使用 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.8</version>
        <scope>provided</scope>
    </dependency>
  </dependencies>

• 编写Controller

  @RestController
  @RequestMapping("stu")
  public class HelloController {
    /**
     * 测试无参数接口地址
       无参：get  http://ip:port/rootPath/stu/hello
     */
    @GetMapping("hello")
    public String hello() {
        return "hello";
    }
    /**
     * 测试 queryString 风格的参入参数
       QueryString(问号传参)：
       get    http://ip:port/rootPath/stu?num=xxx
     */
    @GetMapping
    public Student modifyStudentNum(@RequestParam("num") String num) {
        Student student = new Student(num, "xiaohong", 10, "parts");
        return student;
    }
    /**
     * 测试Restful风格的参入参数
       path(Restful):
       get    http://ip:port/rootPath/stu/xxxx
     */
    @GetMapping("{name}")
    public Student modifyStudentName(@PathVariable("name") String name) {
        Student student = new Student("002", name, 10, "parts");
        return student;
    }
    /**
     * 测试json格式的传入参数
       请求体传参(json格式的数据):
           post http://ip:port/rootPath/stu
           requestBody：
        {
            "xxxxx"："xxxx"
        }
     */
    @PostMapping
    public Student modifyStudent(@RequestBody Student student) {
        student.setName("modifyName");
        return student;
    }
    /**
     * 测试 queryString 、Restful 和 json 格式的参数
       put    http://ip:port/rootPath/stu/xxxx?name=xxx
           requestBody：
        {
            "xxxxx"："xxxx"
        }
     */
    @PutMapping("{id}")
    public Student mofidyStudentBynNum(@PathVariable("id") String id, @RequestParam("name") String name, @RequestBody Student student) {
        student.setName(name);
        student.setStuNo(id);
        return student;
    }
  }
  

• 测试实体类

  package com.xuecheng.env.entity;
  @Data
  @AllArgsConstructor
  public class Student {
    //学员编号
    private String stuNo;
    //学成名称
    private String name;
    //学员年龄
    private int age;
    //学员地址
    private String address;
  
    //getter/setter 省略
  }
  

• 编写 application.yml 中的启动配置

  # Spring Boot 启动参数
  server:
  port: 8080
  servlet:
    context-path: /swagger
  # Spring Boot 集成 Swagger 的集成参数
  swagger:
  enabled: true                          #Swagger 工程开启开关
  base-package: com.xuecheng             #需要生成文档资源所在包
  title: "测试工程"                       #文档的标题
  description: "对 Swagger 的测试程序"    #文档的描述
  version: 1.0.0                         #文档的版本号
  

• 编写 Spring Boot 启动类

  package com.xuecheng.swagger;
  import com.spring4all.swagger.EnableSwagger2Doc;
  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.SpringBootApplication;
  /**
  * <p> Spring Boot 启动类</p>
  */
  @SpringBootApplication   //Spring Boot 启动注解
  @EnableSwagger2Doc       //开启 Swagger 功能
  public class SwaggerTestApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerTestApplication.class,args);
    }
  }
  

• 注意：上面的Spring boot启动类的代码中，必须使用@EnableSwagger2Doc开启Swagger功能

• 运行界面显示

• 服务接口文档地址固定为：服务地址+项目的根路径+ swagger-ui.html

  生成文档说明信息种类

• 上面的案例中，简单的演示了 Swagger 的使用，不难发现 Swagger可以接口信息进行描述，描述主要有一下几类信息

• 工程接口文档的基本信息

• 接口所属的 Controller 信息

• Controller 方法中的接口信息描述

• 上图解释：

  • 注释①：请求方式
  • 注释②：请求地址
  • 注释③：请求参数描述
  • 注释④：响应参数描述

    生成请求参数文档说明

• 其中请求参数方式不同，器描述的信息也有不同，大致有5种类型，分别是：

• 无参接口信息描述

• QueryString 参数接口描述

• Restful 参数接口描述

• 请求体参数（json格式）接口描述

• 多种类型参数描述

• 上面的参数方式描述的信息是 Swagger 对 Spring MVC 注解解析而生产的文档，不同的注解会生产不同的文档描述，这是我们就需要知道哪些注解会影响到 Swagger 生成的文档。

• @Controller

  • Swagger 只会对 Controller 上标注有 @Controller（或@Controller派生注解） 的类生成文档。

    @RestController
    @RequestMapping("stu")
    public class HelloController {
    //省略代码
    }
    

• @RequestMapping

  • Swagger 只会对 Controller 标注有 @RequestMapping（或@RequestMapping派生注解） 方法生成文档。

    @RestController
    @RequestMapping("stu")
    public class HelloController {
    /**
    * 测试Restful风格的参入参数
    */
    @GetMapping("{name}")
    public Student modifyStudentName(@PathVariable("name") String name) {
       Student student = new Student("002", name, 10, "parts");
       return student;
    }
    //省略其他代码
    }
    

• @RequestParam

  • Swagger 对此注解生成 QueryString 的参数方式的文档。

• @PathVariable
  • Swagger 对此注解生成 Restful 的参数方式的文档。

• @RequestBody
  • Swagger 对此注解生成请求体（json）的参数方式的文档。

Swagger 的常用注解

• 在之前 Swagger对Spring MVC的注解生成文档，文档是生成了，但文档对具体的信息没有描述，例下图如：

• 注释①：Controller 具体信息没有信息描述
• 注释②：请求地址没有功能信息描述
• 注释③：传入参数没有具体信息描述

• 注释④：响应信息没有具体信息描

• 既然上面的文档需要具体的信息描述，那我们应该如何解决呢？这里 Swagger 通过注解的方式来描述文档的具体信息。Swagger 的文档描述注解，常用的有两大类文档信息描述注解：

  • Controller 接口描述注解
  • 实体类描述注解

    Controller接口描述注解

• Controller接口描述注解主要用在 Controller 类中或 Controller 实现的接口类上，下面是注解的列表： | 注解名称
  | 作用
  | 标注位置
  | | —- | —- | —- | | [@Api](https://itheima-sh.yuque.com/Api)
  | 对Controller接口信息描述
  | 类上
  | | @ApiOperation
  | 对Controller方法功能描述
  | 方法上(常用)或类上
  | | [@ApiImplicitParams](https://itheima-sh.yuque.com/ApiImplicitParams)
  | 对Controller方法多个请求参数信息描述
  | 方法上(常用)、注解、类上
  | | @ApilmplicitParam
  | 对Controller方法一个请求参数信息描述
  | **方法上
  |

• 下面是 Controller 接口描述注解的使用:

  • 方式一：标注在 Controller上

• 上图中解释：
  • 注释①：@Api 对 Controller文档描述
  • 注释②：@ApiOperation 对方法进行描述
  • 注释③：@ApilmplicitParam 对方法一个参数的描述
  • 注释④：@ApilmplicitParams 对方法多个参数的描述
• 方式二：标注在 Controller实现的接口上（推荐 ）
  • 接口声明

如果出弹窗，选择NO

package com.xuecheng.swagger.controller;

import com.xuecheng.swagger.pojo.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

/**
 * @author: Mr.W
 * @date: 2022/6/15
 * @description:
 */
@Api(value = "Hello Controller", tags = "Hello Controller api 接口", description = "Hello Controller api 接口--desc")
public interface HelloApi {

    @ApiOperation("学员编号")
    @ApiImplicitParams({
            /**
             * 参数解释：
             *      id：参数名称
             *      value：对参数的描述
             *      required：是否必须要传参
             *      dataType：参数类型
             *      paramType:传参方式（Valid values are path, query, body, header or form.）
             */
            @ApiImplicitParam(name = "id", value = "学员id", required = true, dataType = "String", paramType = "path"),
            @ApiImplicitParam(name = "name", value = "学员姓名", required = true, dataType = "String", paramType = "query")
            //@ApiImplicitParam(name = "student", value = "", required = true, dataType = "Student", paramType = "body")
    })
    Student mofidyStudentBynNum(String id,
                                String name,
                                Student student);
}

• 上图中解释：
  • 注释①：@Api 对 Controller文档描述
  • 注释②：@ApiOperation 对方法进行描述
  • 注释③：@ApilmplicitParam 对方法一个参数的描述
  • 注释④：@ApilmplicitParams 对方法多个参数的描述
• Controller 实现接口方法

• 生成页面文档效果：
  • Controller 提供接口地址和方法功能描述

• Controller 方法参数的描述

文档的生成我们使用相关的注解里的属性来对文档的某些信息进行描述，下面是各个注解属性的解释。

@Api 注解属性

@ApiOperation

@ApiImplicitParam

实体类描述注解

• 在 Controller 的方法中，参入和传出参数有时是一个实体类，而实体类的属性信息并没有在接口文档中描述，如下图：

• 注释①：参入参数没有信息描述
• **注释②：传出参数没有信息描述

**

• Swagger对此也提供了实体类描述注解，分表对实体类和实体类属性进行描述

• 下面是注解的列表： | 注解名称
  | 作用
  | 标注位置
  | | —- | —- | —- | | [@ApiModel](https://itheima-sh.yuque.com/ApiModel)
  | 对方法中实体类的信息描述
  | 类上
  | | @ApiModelProperty
  | 对方法中实体类的属性信息描述
  | **属性上
  |

• 下面是实体类描述注解的使用：

• 在实体类中使用

• 生成页面文档效果：

• 注释①：参入参数信息描述

• 注释②：传出参数信息描述

  YApi 环境部署

• YApi 的安装需要安装两个环境：

  • MongoDB（YApi使用的数据库）
  • YApi 服务

• Yapi 官方github地址：https://github.com/YMFE/yapi

  MongoDB 环境安装

  拉取镜像

  docker pull mongo:4.4
  

  安装容器

  docker run -d \
  --name mongo-yapi \
  -v /usr/soft/mongo/data/:/usr/soft/mongo/data \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=anoyi \
  mongo:4.4
  

  YApi 环境安装

  拉取镜像

  docker pull registry.cn-hangzhou.aliyuncs.com/anoyi/yapi
  

  创建 YApi 的工作目录

  #创建目录
  mkdir -p /usr/soft/yapi/config
  #进入到目录中
  cd /usr/soft/yapi/config
  

  在此目录中创建 yapi的配置文件 config.json

  {
  "port": "3000",
  "adminAccount": "admin@anoyi.com",
  "timeout":120000,
  "db": {
    "servername": "mongo",
    "DATABASE": "yapi",
    "port": 27017,
    "user": "admin",
    "pass": "anoyi",
    "authSource": "admin"
  }
  }
  

  在 /usr/soft/yapi/config 中执行下面命令来初始化 yapi 的数据库索引及管理员账号

  docker run -it --rm \
  --link mongo-yapi:mongo \
  --entrypoint npm \
  --workdir /yapi/vendors \
  -v $PWD/config.json:/yapi/config.json \
  registry.cn-hangzhou.aliyuncs.com/anoyi/yapi \
  run install-server
  

  初始化后便可以得到 yapi 的默认账号

• 账号名：”admin@anoyi.com“

• 密码：”ymfe.org”

• 在 /usr/soft/yapi/config 中执行下面命令来创建容器

  docker run -d \
  --name yapi \
  --link mongo-yapi:mongo \
  --workdir /yapi/vendors \
  -p 3000:3000 \
  -v $PWD/config.json:/yapi/config.json \
  registry.cn-hangzhou.aliyuncs.com/anoyi/yapi \
  server/app.js
  

• 创建好后，便可以通过浏览器地址进行访问：http://ip地址:3000

  接口导入

  
  

• 新建一个json文件，复制进去

其他开发工具

• 下面需要介绍一下项目开发前的两个内容：
• 项目代码生成器

• 项目开发规范文档

  项目代码生成器

• 考虑到后期也项目业务代码繁杂，编写基础性的代码会成为浪费项目开发时间。为了提高项目开发速度，又考虑到项目的数据库的持久层为：Mybatis Plus ，我们可以使用 Mybatis Plus 官方提供的代码生成器来对项目中的基础代码进行。
  Mybatis Plus 代码生成器：https://baomidou.com/guide/generator.html

  项目导入

  在学成在线项目中将会对代码生成器进行了封装，并提供了对应的项目来生成开发中的基础代码。在今天下发资料中 “\资料\代码生成器工程\xc-mp-generator.7z” ，将其解压并发送 xc-parent 工程下。
  

• 并在 xc-parent 工程下的 pom 文件中添加子模块的管理配置，如下：

  <!-- 对子项目进行聚合管理 -->
  <modules>
    <module>xc-common</module>
    <module>xc-api</module>
    <module>xc-content-service</module>
    <!-- 添加子模块 -->
    <module>xc-mp-generator</module>
  </modules>
  

• 下面是 xc-mp-generator 中的代码生成器的核心代码，如下图：

• 代码生成器示意图
  

• PS：

  • 上面是针对学成在线每一个业务模块来生成的代码。
  • 比如说，内容管理微服务代码生成器：ContentCodeGenerator
    • 后面就会使用上面的代码生成器来生成每一个模块下的基础代码。

      代码生成参数说明

• 每一个代码生成器中都包含下面上个重要参数，如下：

  • 数据库相关配置参数
  • 是否生成 DTO 数据
• 数据库相关配置参数（数据库的名称）
• 代码生成其会根据数据库的内容来动态的生成代码，所有下面需要对数据库内容进行对应的配置。
• 数据库相关配置参数说明

• 上图解释：
  • 注释①：修改服务名称，也是数据库的名称：xc_后缀名称。
    • 由于是内容管理，名称为：content。
  • 注释②：修改数据库参数。
    • 数据账号和密码，对课程基本信息报生成相关代码。
  • 注释③：数据库表的名称。
    • 我们需要生成哪张表的基础代码，就需要填写对应的表的名称。
• 是否生成 DTO 数据。
  • 在后端业务操作时，会涉及到实体类对象的数据转换数据传输对象 DTO ，

• 注释：通过修改 IS_DTO 来生成 DTO 实体类。

  • true：生成 DTO 实体类。
  • false：生成 PO 实体类。

    代码生成

• 下面将通过内容管理服务的代码生成器 ：ContentCodeGenerator，来生成内容管理的代码。

• 运行main方法

• PS：在生成前，请先确认内容管理对应的数据库 xc_content 在数据库创建出来，否则无法生成对应的代码。
  运行后就会在 xc-mp-generator 的 src/main/java 下生成对应的基础代码，如下图：
• 代码生成示意图

• 对于生成后的代码我们需要拷贝到内容管理微服务中，如下图：
• 拷贝资源

项目开发规范文档

• 学成在线在进行开发时，会提供项目团队开发的规范文档。规范文档主要的作用是规范代码编写，提高代码结构的一致性和代码的可读性，大大提高项目的协作能力和维护能力。
• 对于学成在线来说，规范项目内容主要有几方面：
  • 代码编写的规范
  • 前后端交互的URL接口规范
  • 项目内容结构的规范
• 在今天下发资料中 “/资料/开发规范/项目开发规范文档.md” 中通过 10 点来描述上面的三项内容。

扩展
1.jsr规范：
https://zh.wikipedia.org/wiki/JCP
2.java 8 日期
https://lw900925.github.io/java/java8-newtime-api.html