前后端项目结构规范性记录

2021年9月15号更新

【强制】前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体。
说明：
1） 协议：生产环境必须使用 HTTPS。
2） 路径：每一个 API 需对应一个路径，表示 API 具体的请求地址：
a） 代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。
b） URL 路径不能使用大写，单词如果需要分隔，统一使用下划线。
c） 路径禁止携带表示请求内容类型的后缀，比如".json",".xml"，通过 accept 头表达即可。
3） 请求方法：对具体操作的定义，常见的请求方法如下：
a） GET：从服务器取出资源。
b） POST：在服务器新建一个资源。
c） PUT：在服务器更新资源。
d） DELETE：从服务器删除资源。
4） 请求内容：URL 带的参数必须无敏感信息或符合安全要求；body 里带参数时必须设置 Content-Type。
5） 响应体：响应体 body 可放置多种数据类型，由 Content-Type 头来确定

【强制】服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，errorCode、
errorMessage、用户提示信息四个部分。
说明：四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息
要求：简短清晰、提示友好，引导用户进行下一步操作或解释错误原因，提示信息可以包括错误原因、上
下文环境、推荐操作等。 errorCode：参考附表 3。errorMessage：简要描述后端出错原因，便于错误排
查人员快速定位问题，注意不要包含敏感数据信息。
正例：常见的 HTTP 状态码如下
1） 200 OK: 表明该请求被成功地完成，所请求的资源发送到客户端。
2） 401 Unauthorized: 请求要求身份验证，常见对于需要登录而用户未登录的情况。
3） 403 Forbidden：服务器拒绝请求，常见于机密信息或复制其它登录用户链接访问服务器的情况。
4） 404 Not Found: 服务器无法取得所请求的网页，请求资源不存在。
5） 500 Internal Server Error: 服务器内部错误

【强制】对于需要使用超大整数的场景，服务端一律使用 String 字符串类型返回，禁止使用Long 类型。
说明：Java 服务端如果直接返回 Long 整型数据给前端，JS 会自动转换为 Number 类型（注：此类型为双
精度浮点数，表示原理与取值范围等同于 Java 中的 Double）。Long 类型能表示的最大值是 2 的 63 次方
-1，在取值范围之内，超过 2 的 53 次方 (9007199254740992)的数值转化为 JS 的 Number 时，有些数
值会有精度损失。扩展说明，在 Long 取值范围内，任何 2 的指数次整数都是绝对不会存在精度损失的，所
以说精度损失是一个概率问题。若浮点数尾数位与指数位空间不限，则可以精确表示任何整数，但很不幸，
双精度浮点数的尾数位只有 52 位。
反例：通常在订单号或交易号大于等于 16 位，大概率会出现前后端单据不一致的情况，比如，"orderId": 
362909601374617692，前端拿到的值却是: 362909601374617660

【推荐】不要在视图模板中加入任何复杂的逻辑。
说明：根据 MVC 理论，视图的职责是展示，不要抢模型和控制器的活。
【推荐】任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。
【推荐】及时清理不再使用的代码段或配置信息。
说明：对于垃圾代码或过时配置，坚决清理干净，避免程序过度臃肿，代码冗余。
正例：对于暂时被注释掉，后续可能恢复使用的代码片断，在注释代码上方，统一规定使用三个斜杠(///)
来说明注释掉代码的理由。如：
 public static void hello() {
 /// 业务方通知活动暂停
 // Business business = new Business();
 // business.active();
 System.out.println("it's finished");
}

专有名词解释

1. POJO（Plain Ordinary Java Object）: 在本规约中，POJO 专指只有 setter/getter/toString 的
   简单类，包括 DO/DTO/BO/VO 等。
2. DO（Data Object）：阿里巴巴专指数据库表一一对应的 POJO 类。此对象与数据库表结构一
   一对应，通过 DAO 层向上传输数据源对象。
3. DTO（Data Transfer Object）：数据传输对象，Service 或 Manager 向外传输的对象。
4. BO（Business Object）：业务对象，可以由 Service 层输出的封装业务逻辑的对象。
5. Query：数据查询对象，各层接收上层的查询请求。注意超过 2 个参数的查询封装，禁止使用
   Map 类来传输。
6. VO（View Object）：显示层对象，通常是 Web 向模板渲染引擎层传输的对象。
7. AO（Application Object）: 阿里巴巴专指 Application Object，即在 Service 层上，极为贴近
   业务的复用代码。
8. CAS（Compare And Swap）：解决多线程并行情况下使用锁造成性能损耗的一种机制，这是
   硬件实现的原子操作。CAS 操作包含三个操作数：内存位置、预期原值和新值。如果内存位
   置的值与预期原值相匹配，那么处理器会自动将该位置值更新为新值。否则，处理器不做任何
   操作。
9. GAV（GroupId、ArtifactId、Version）: Maven 坐标，是用来唯一标识 jar 包。
10. OOP（Object Oriented Programming）: 本文泛指类、对象的编程处理方式。
11. AQS（AbstractQueuedSynchronizer）: 利用先进先出队列实现的底层同步工具类，它是很多上
    层同步实现类的基础，比如：ReentrantLock、CountDownLatch、Semaphore 等，它们通
    过继承 AQS 实现其模版方法，然后将 AQS 子类作为同步组件的内部类，通常命名为 Sync。
12. ORM（Object Relation Mapping）: 对象关系映射，对象领域模型与底层数据之间的转换，本
    文泛指 iBATIS, mybatis 等框架。
13. NPE（java.lang.NullPointerException）: 空指针异常。
14. OOM（Out Of Memory）: 源于 java.lang.OutOfMemoryError，当 JVM 没有足够的内存
    来为对象分配空间并且垃圾回收器也无法回收空间时，系统出现的严重状况。
15. 一方库: 本工程内部子项目模块依赖的库（jar 包）。
16. 二方库: 公司内部发布到中央仓库，可供公司内部其它应用依赖的库（jar 包）。
17. 三方库: 公司之外的开源库（jar 包）

---

前言

以前对这块并没有去具体了解，就是简单的了解了一些小demo的开发流程。这次对这块写个记录。

---

后端

分享一篇微信上的文章：《优秀的项目代码是怎样分层的》，这是来自B站一个Up主codesheep的文章。
还有一篇文章：《Java命名规范》https://mp.weixin.qq.com/s/fY9crroOviqmstTZZIM5Ew
接下里其实见得最多的就是阿里的这张图以及阿里的解释

图片解释：

• 开放 API 层：可直接封装 Service 接口暴露成 RPC 接口；通过 Web 封装成 http 接口；网关控制层等。
• 终端显示层：各个端的模板渲染并执行显示的层。当前主要是 velocity 渲染，JS 渲染，JSP 渲染，移
动端展示等。
• Web 层：主要是对访问控制进行转发，各类基本参数校验，或者不复用的业务简单处理等。
• Service 层：相对具体的业务逻辑服务层。
• Manager 层：通用业务处理层，它有如下特征：
1） 对第三方平台封装的层，预处理返回结果及转化异常信息，适配上层接口。
2） 对 Service 层通用能力的下沉，如缓存方案、中间件通用处理。
3） 与 DAO 层交互，对多个 DAO 的组合复用。
• DAO 层：数据访问层，与底层 MySQL、Oracle、Hbase、OB 等进行数据交互。
• 第三方服务：包括其它部门 RPC 服务接口，基础平台，其它公司的 HTTP 接口，如淘宝开放平台、支
付宝付款服务、高德地图服务等。
• 外部数据接口：外部（应用）数据存储服务提供的接口，多见于数据迁移场景中。

分层领域模型规约：
• DO（Data Object）：此对象与数据库表结构一一对应，通过 DAO 层向上传输数据源对象。
• DTO（Data Transfer Object）：数据传输对象，Service 或 Manager 向外传输的对象。
• BO（Business Object）：业务对象，可以由 Service 层输出的封装业务逻辑的对象。
• Query：数据查询对象，各层接收上层的查询请求。注意超过 2 个参数的查询封装，禁止使用 Map 类
来传输。
• VO（View Object）：显示层对象，通常是 Web 向模板渲染引擎层传输的对象。

尽量对整个Maven工程结构进行分层拆分，增加工程的可扩展性，实现高内聚低耦合的开发要求。
例子：图中将工程拆分为一个父工程和三个子工程：
•CancerCenter：父工程，只有POM的约束，无具体业务代码。
•CancerCenter_Common：通用工程，最下层依赖，包含utils，model，exception等整个项目的公共模块，提供整个项目的基础支撑。
•CancerCenter_Service：业务工程，向下依赖于Common，向上被Web依赖，包含service和mapper，是整个项目的核心业务。
•CancerCenter_Web：Web工程，向下依赖于Service，对外提供接口，包含接口、配置等Web项目独有的模块。

---

前端

1.资源路径编译规则
默认情况下，vue-loader 使用 css-loader 和 Vue 模版编译器自动处理样式和模版文件。在编译过程中，所有的资源路径例如 、background: url(...) 和 @import 会作为模块依赖。
路径的编译规则如下：
如果路径是绝对路径，会原样保留；
如果路径以 . 开头，将会被看作相对的模块依赖，并按照你的本地文件系统上的目录结构进行解析；
如果路径以 @ 开头，也会被看作模块依赖。如果你的 webpack 配置中给 @ 配置了 alias，这就很有用了。所有 vue-cli 创建的项目都默认配置了将 @ 指向 /src；

2.build目录和config目录
build 目录下存放的是 webpack 的配置文件；
config 目录下存放的是与项目构建相关的常用的配置选项、变量；
通常情况下，除非要配置 webpack 的 loader 或者 插件，否则，你应该优先尝试更改 config 目录下的文件；

​

3.src目录
根据项目结构的核心思想，src的目录结构将以业务功能划分。
注意事项：
I . 项目的业务代码应该从 src/app/ 目录开始；
II . src/common/ 的子目录中，在深度上的层级结构应该是尽量扁平的，不应该有很深的层级结构；如果 src/common/ 中的目录树 与 src/app/ 中的目录树在深度上有十分相似的层级结构，则就表示你应该重新考虑 src/common/ 中的资源是否是真的需要被共享的资源，被共享的资源的目录层级结构应该是尽可能扁平的；对于不必共享的资源，应该放在 src/app/ 下相应的目录结构中；
III . src文件或文件夹的组成分为3种。直接在src目录下的vue文件是工程内直接于业务相关页面文件；components文件夹下是组件文件；其他文件夹是一些活动和主业务耦合性不大的文件。

4.static目录
static目录可以添加任何资源，如：图片、代码 等等。不过工程内图片大多存放七牛，static/project.js存放公共函数

微信文章：https://mp.weixin.qq.com/s/mNWc2tJWZlxJkKQh-kNpVg；可以参考一下，做个简单的前端认识。
下图来自于该篇文章。

---

最后

平时没事可以看看《阿里开发手册》，有助于对Java项目的开发流程的认识以及对规范的认识，可以有个良好的开发习惯。