微服务开发手册

微服务开发手册开发说明●所有服务均基于springboot框架开发。Springboot内嵌了tomcat服务器，无需生成war包，并简化了maven配置，能够让开发者快速入手spring的开发。●服务的接口定义需严格符合restful规范。rest规范参考第2节restapi接口规范●所有服务都需要在注册服务上注册，否则不能被其他服务所调用。同时平台也能够实时监测服务的状态，能够及时预警及调度资源。●所有服务的配置信息统一保存于gitlab上，并通过配置服务获取配置。●对数据库的操作统一采用MyBatis

框架。MyBatis是个支持普通SQL查询，\t":///blank"存储过程和高级映射的优秀\t":///blank"持久层框架。Springboot也提供了mybatis的集成方案，可以很快捷地整合mybatis到项目中。●包名约定：所有包均以com.drht.服务名为父包名，如com.drht.auth，后面再跟具体模块名称作为子包名。●所有项目基于jdk1.8来开发。项目的管理与构建采用maven，代码统一托管于gitlab仓库。restapi接口规范springboot接口设计需符合restful风格。在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。而客户端要执行某种类型的操作，需要根据的操作协议来决定。提供了常用的几种操作，如下表：动作说明GET（SELECT）从服务器取出资源（一项或多项）POST（CREATE）在服务器新建一个资源。PUT（UPDATE）在服务器更新资源（客户端提供改变后的完整资源）。PATCH（UPDATE）在服务器更新资源（客户端提供改变的属性）。DELETE（DELETE）从服务器删除资源。对数据库的增删改查操作，应该严格遵守上面定义的五种动作。对于更新动作，参数通过requestbody来传递，格式为json。服务端返回数据格式也均为json。服务端返回数据对象约定：publicclassUnifyInfo{ privateintcode;//返回代码，1：成功，0：失败 privateStringmessage;//返回信息提示 privateStringprompt;// privateStringpath;//一般用于错误时的跳转路径 privateHashMap<String,?>attribute;//一般用于查询时的返回数据内容}Springboot会自动将符合javabean格式的对象转换为json格式数据返回。示例：客户端请求请求参数服务端返回数据说明GET/users{"code":"1","message":"查询成功","prompt":"","path":"","users":[]}查询所有用户GET/users/ID{"code":"1","message":"查询成功","prompt":"","path":"","users":[]}查询指定ID的用户POST/users{"username":"user2","email":"666633433@"}{"code":"0","message":"创建用户失败","prompt":"该用户已经存在","path":"://localhost:8080/users","result":{}}创建一个用户PUT/users/ID{"username":"user2","email":"666633433@"}{"code":"1","message":"创建用户成功","prompt":"","path":"","result":{}}更新某用户信息PATCH/users/ID{"username":"user2","email":"666633433@"}{"code":"1","message":"更新成功","prompt":"","path":"","result":{}}更新某用户指定字段DELETE/users/ID{"code":"1","message":"删除成功","prompt":"","path":"","result":{}}删除指定用户而对于登录、登出操作，可以理解为登录是创建token,登出是删除token,所以可以用POST和DELETE来定义这两种接口。刷新token是更新操作所以用PUT。配置文件管理所有服务的配置文档均保存于gitlab上，并通过配置服务config-service来获取配置。每个服务在gitlab均保存一份以服务id命名的properties文件。以服务spring-boot-demo为例，其在gitlab上的配置文件为perties，文件名对应于该服务的perties中配置的的value值。如果名称不一致，配置服务将拿不到正确的配置信息。在perties中通常配置该服务的启动端口、数据库连接参数等信息。当该文件有更新并push到gitlab后，配置服务会自动通知客户端服务更新配置信息。关键配置：在主程序中需要访问配置文件的类名上加上注解：@RefreshScope，如果没有该注解，配置服务将不能主动通知客户端服务更新配置。如下：@RefreshScope@RestControllerpublicclassMessageRestController{@Value("${message:Hellodefault}")privateStringmessage;@RequestMapping("/message")StringgetMessage(){returnthis.message;}}当perties文件里的message变量发生变化后，请求/message时返回的message值将是更新后的message内容。pom.xml关键依赖项：<dependency><groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-config-client</artifactId></dependency><dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId></dependency>同时需要引入springcloud的依赖项<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>Camden.SR5</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>在src/main/resouce目录建立perties文件，设置配置服务url与serviceperties文件内容：#配置服务地址spring.cloud.config.uri=://3:9999#service=spring-boot-demo注：不能在perties设置配置服务的url,因为perties的启动优先级最低，不能在程序启动之前读取到配置服务url,从而不能加载配置服务上相应的配置。服务注册register-service提供服务的注册与发现。所有的服务都需要注册到register-service中，否则不能够被其他服务发现与调用，比如路由服务。关键配置pom.xml关键依赖项：<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-eureka-server</artifactId></dependency>同时需要引入springcloud的依赖项<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>Camden.SR5</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>主程序加上注解：@EnableEurekaServer如下：@EnableEurekaServer@SpringBootApplicationpublicclassRegisterServiceApplication{publicstaticvoidmain(String[]args){SpringApplication.run(RegisterServiceApplication.class,args);}}对应配置服务器上的perties中添加注册服务的地址。perties配置如下：#服务启动端口server.port=8082#注册服务地址eureka.client.serviceUrl.defaultZone=://3:9998/eureka/统一网关路由所有rest请求均需要通过网关来路由到具体的服务。网关服务能起到负载均衡、动态路由、统一认证等功能。使用代理服务能够避免必须的跨域资源共享（Cross-OriginResourceSharing）。当一个UI应用调用一个或更多的后端服务的时候，通过网关服务来做统一的代理。前端应用不再需要关心后台业务服务的具体地址，因此当业务服务的地址变更后也不需要修改应用端的配置。所有的请求都在网关做了统一的认证授权，因此业务服务也不再需要考虑与授权有关的问题。

按照约定,一个serviceid为"userservice"的服务会收到

/userservice请求路径的代理请求(前缀会被剥离)。因此要查询用户ID是590d38b064328b1aac828ae6的信息，完整的请求路径是://<gateway>:<port>/userservice/users/590d38b064328b1aac828ae6其中userservice是userservice的sericeid,users/{id}是该服务提供的对外访问接口。网关服务会自动根据请求路径里的serviceid（本例中是userservice）找到userservice的请求地址，并路由给该服务的users/{id}接口，其最终的路由地址是://<userservice>:<port>/users/590d38b064328b1aac828ae6。注：url不包括/userservice。而网关服务能够正确路由的前提是userservice已经在注册服务上注册。认证授权对于某用户的授权分为两类，一类是该用户是否能够访问某些url,一类是它在界面上所能看到哪些功能（即菜单）。应用端访问后台服务时均需要经过授权服务auth-service认证才能访问服务的资源。授权服务对资源的访问控制通过uri+serviceid+METHOD来控制，如角色ROLEUSER的资源权限为服务名为userservice的user/*,请求方式为ALL,则其对所有userservice服务的uri为user/形式的资源均有权访问。如POST://<ip>:<port>/user/addGET://<ip>:<port>/user/query所以在设计api接口时，需严格按照第一节中restapi的规范定义接口，以方便对某一类资源的请求做统一的权限配置。同时在应用端，某用户登录进来后能够访问的菜单也是通过授权服务控制。菜单资源包括菜单的名称，图标，跳转路径等属性。应用端通过授权得到的菜单属性，并决定菜单界面的布局。菜单对象定义如下：publicclassMenu{privateIntegerid;privateStringmenuname;privateIntegerparentid;privateStringmenucode;privateStringmenuurl;privateStringmenuicon;privateStringurltarget;privateIntegerisactive;privateIntegernavmenu;privateIntegerisleaf;privateIntegerviewtype;privateIntegersort;privateStringremark;privateStringcreator;privateStringmodified;privateDatecreatetime;privateDatelastupdate;}持续集成项目开发完成后，通过jenkins持续集成，打包成docker镜像后上传到服务器上的dockerrepository后运行，所以需要在pom.xml文件里配置mavendocker插件。Pom.xml关键配置：<resources><!--使用@@站位符，输出Dockerfile至docker文件夹--> <resource> <directory>src/main/resources</directory> <includes> <include>**/*</include> </includes> <filtering>false</filtering> </resource> <resource> <directory>src/main/java</directory> <includes> <include>**/*.properties</include> <include>**/*.xml</include> </includes> <filtering>false</filtering> </resource> </resources><plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <fork>true</fork> </configuration> </plugin> <plugin> <groupId>com.spotify</groupId> <artifactId>docker-maven-plugin</artifactId> <version>0.4.11</version> <configuration> <imageName>3:5000/${project.artifactId}</imageName> <dockerDirectory>src/main/docker</dockerDirectory> <pushImage>true</pushImage> <resources> <resource> <targetPath>/</targetPath> <directory>${project.build.directory}</directory> <include>${project.build.finalName}.jar</include> </resource> </resources> </configuration> </plugin> </plugins>在src/main/下建立docker目录，并新建Dockerfile，内容如下：FROMjava:8VOLUME/tmpADDspring-boot-demo-0.0.1-SNAPSHOT.jarapp.jarEXPOSE8080CMDjava-jarapp.jar当程序经过测试并提交到gitlab后，jenkins将自动构建并打包成docker镜像发布到远程docker仓库。同时jenkins会通知远程服务下载该镜像并重新运行。集成mybatis所有数据库操作采用Mybatis来管理。集成Mybatis关键配置如下：添加pom.xm依赖<dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>1.3.0</version> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter-test</artifactId> <version>1.3.0</version> </dependency><!--以mysql数据库为例--> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>5.1.40</version> </dependency>Sperties(托管于gitlab上,由配置服务统一管理)主要配置如下：mybatis.config-location=classpath:.drht.demo.mapper=TRACEspring.datasource.driverClass=com.mysql.jdbc.Driverspring.datasource.username=rootspring.datasource.password=123456spring.datasource.url=jdbc:mysql://:3306/test?useUnicode=true&characterEncoding=utf-8资源的配置结构如下图：其中mybatis-config.xml内容：<!DOCTYPEconfigurationPUBLIC"-////DTDConfig3.0//EN"":///dtd/mybatis-3-config.dtd"><configuration><typeAliases><packagename="com.drht.domain"/></typeAliases><mappers><mapperresource="com/drht/mapper/CityMapper.xml"/></mappers></configuration>CittyMapper.xml内容如下：<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEmapperPUBLIC"-////DTDMapper3.0//EN"":///dtd/mybatis-3-mapper.dtd"><mappernamespace="com.drht.mapper.CityMapper"> <selectid="selectCityById"resultType="City"> select*fromcitywhereid=#{id} </select> <deleteid="deleteCityById"> deletefromcitywhereid=#{id} </delete> <insertid="insertCity"parameterType="com.drht.domain.City"> insertintoCity(id,name,state,country) values(#{id,jdbcType=INTEGER},#{name,jdbcType=VARCHAR}, #{state,jdbcType=VARCHAR}, #{country,jdbcType=VARCHAR}) </insert></mapper>该配置文件定义了三种数据库操作，对应了CityMapper这个接口中的三种方法@MapperpublicinterfaceCityMapper{ CityselectCityById(intcityid); voidinsertCity(Citycity); voiddeleteCityById(intcityid);}附录一：完整pom.xml<projectxmlns=":///POM/4.0.0"xmlns:xsi="://./2023/XMLSchema-instance" xsi:schemaLocation=":///POM/4.0.0:///xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.drht</groupId> <artifactId>spring-boot-demo</artifactId> <version>0.0.1-SNAPSHOT</version> <name>spring-boot-demo</name> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.5.1.RELEASE</version> </parent> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>1.3.0</version> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter-test</artifactId> <version>1.3.0</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>5.1.40</version> </dependency> <!--<dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency>--> <!--testdependencies--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-config</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-eureka</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-eureka-server</artifactId> <scope>test</scope> </dependency> </dependencies> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>Camden.SR5</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <build> <resources><!--使用@@站位符，输出Dockerfile至docker文件夹--> <resource> <directory>src/main/resources</directory> <includes> <include>**/*</include> </includes> <filtering>false</filtering> </resource> <resource> <directory>src/main/java</directory> <includes> <include>**/*.properties</include> <include>**/*.xml</include> </includes> <filtering>false</filtering> </resource> </resources> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <fork>true</fork> </configuration> </plugin> <plugin> <groupId>com.spotify</groupId> <artifactId>docker-maven-plugin</artifactId> <version>0.4.11</version> <configuration> <imageName>3:5000/${project.artifactId}</imageName> <dockerDirectory>src/main/docker</dockerDirectory> <pushImage>true</pushImage> <resources> <resource> <targetPath>/</targetPath> <directory>${project.build.directory}</directory> <include>${project.build.finalName}.jar</include> </resource> </resources> </configuration> </plugin> </plugins> </build></project>附录二：spring-boot-demo源码（略）

对教材资源的一些讨论摘要：本文就笔者在使用北京师范大学版的实验教材（数学第六册）过程中，对教材资源中的问题进行了理解、分析和建议。关键词：科学性；真实性；层次性；繁琐性；误解。

2023年，我有幸参加了新课改实验教材的教学工作，教材一拿到手，我就被那些花花绿绿、生动形象的图文吸引了，并下定决心，一定要深钻教材，认真研究。在我使用它的近两年的时间里，我发现新教材的可行性特别强，学生脑子灵活、能力强，与此同时我也有太多感受，现仅对教材资源与大家商榷：我们学校是2023年开始使用北师大版新教材的，其中一些图文我认为容易造成学生的误解，不利于学生进行有效的学习。图例的科学性第六册数学书第13页，看一看，说一说下面哪些图形是对称图形（如图1）图1图2红旗应向一个方向飘，除非旗杆那里有电子吹风机（我想是没有的），这幅图有失真实性，孩子们的争议比较大，有的说不看红旗，就建筑来说是对称图形；有的说这幅图形对折不能完全重合，说明不是对称图形等等。我不知道编者的本意是就是通过这些细节考察学生对对称图形的掌握程度，还是根本没想到我们的学生会“盯”的这么仔细，但不管怎么样这幅图不符合实际。选编的练习容易引起误解第六册数学书第55页画一画⑴请你在每种图形的周围画几个与它相同的图形，使它们铺满整个长方形。（如图2）实际上它是铺不满整个长方形的，学生绞尽脑汁想都未能铺满它，其实这道题的目的是利用平移画图形，所以建议把后半句改为“最多能画几个”等类似的语句。再如同上册第66页，（如图3）图3这样的问题容易让孩子误填为苹果占全部水果的1/2，梨子占全部水果的1/2，因为苹果是两种水果中的一种嘛，而这样一填第3问似乎就没有意义了，所以建议问题应改为苹果的个数占全部水果个数的几分之几，梨子的个数占全部水果个数的几分之几。再比如第七册第15页，直线的画法，很容易让孩子误以为直线上有两点。选编的练习容易占用孩子过多的时间数学来源于生活，生活中有许多数学素材，可有时看起来类似的数学素材就拿来选编，容易引起孩子无休止的争论，占用过多的时间。比如学习对称图形这一章，第六册第15页让学生判断蝴蝶（如图4）、第六册第88页判断标志牌（如图5）是否是对称图形，每次孩子都会说不看蝴蝶身上的花纹，它是对称图形，算上花纹它就不是对称图形；不看标志牌里的图形，光看外观图形它是对称图形，全部算上它不是对称图形，看起来学生已完全掌握判断对称图形的要领。可是让它在下面小小的括号里填对称还是不对称呢。我看在这没有必要让学生这样花费工夫、精力和时间。图4图5选编的练习让孩子得到的结果缺乏真实性第七册第39页第5题：我国于2023年12月30日成功地发射了“神舟”四号航天飞船，它环绕地球107圈后返航，每一圈的时间约是89分。估计从起飞到返航约是多少分？这一道题如果列式准确计算是：89×107=9523（分），准确地说应该是开始绕地球旋转到返航需要9523分钟，那么从起飞到返航的时间应超过9523分。但一般的学生都会这样估算：89×107≈90×100=9000（分），几乎没有人这样估算：89×107≈100×100=10000（分）或89×107≈90×107=9630（分），按问题来说这道题要符合实际只能估大不能估小，不然还没等返航就从天上掉下来了。选编的题例过于简单在新教材素材的选编上，往往出现题例简单而练习又偏难的现象，这会让孩子感觉压力大、学习吃力。例如：第七册乘法分配律教学中，教材是让学生发现、抽象出乘法分配律后，直接利用乘法分配律进行简单的简便计算，而紧接着在练一练的第二题出现了99×11、38×29+38这样的题，大