當前位置:網站首頁>【項目總結】項目開發規範

【項目總結】項目開發規範

2022-01-27 00:44:53 胡毛毛_三月

目錄

背景

後端規範像Java一般就可以參考阿裏巴巴Java開發手册,前端也有其自己的規範,詳細的可以參考他們。這篇文章主要定義在開發中的一些業務相關的規範,提高團隊開發效率,提昇代碼的可讀性和可維護性。

後端規範

一、接口api規範

1.接口風格接口風格統一采用restful規範

  • GET請求用於查詢
  • POST請求用於新增
  • PUT請求用於修改
  • DELETE請求用於删除

ps:特殊查詢/删除資源請求GET/DELETE不能使用,可使用POST請求

restful風格規範可參考阮一峰的網絡日志:

2.接口api命名規範

  • 接口統一命名格式=="/api/數據庫錶名/業務名"==
  • 錶名和業務名統一采用“-”符號連接(多單詞),例如:GET、"/api/user/user-job-role"——查詢用戶及崗比特和角色信息
  • 如果是對單錶進行增删改查操作,可省略業務名,例如:POST、"/api/user"——代錶新增一條用戶數據

3.接口參數規範

  • GET/DELETE請求參數規範(參數在請求頭攜帶)

    • 一般按照主鍵id查詢或者删除,或者查詢、删除條件少,選擇一個參數遵循如下規範:

      • api路徑:"/api/數據庫錶名/業務名/{參數名}",例如"/api/user/{id}"。前端請求為“/api/user/1”

      • 在路徑上加的參數,添加注解@PathVariable,在swagger參數後設置paramType = "path",說明參數是在路徑上拼接的,而不是寫在params中。

        @GetMapping("/{id}")
            @ApiOperation(value = "查詢一條用戶錶信息", notes = "根據主鍵id查詢 \n author:RenShiWei")
            @ApiImplicitParam(name = "id", value = "用戶錶id", paramType = "path")
            public ResponseResult<User> userFindById ( @PathVariable Long id ) {
                  
                User user = userService.getById(id);
                if (ObjectUtil.isNull(user)) {
                  
                    log.error("【查看用戶錶失敗");
                    return ResponseResult.ok(ResponseEnum.DATA_NOT_FOUND);
                }
                return ResponseResult.ok(user);
            }
        
  • POST/PUT請求參數規範(參數在請求體攜帶)

    • 對於參數是錶的實體類,强烈建議封裝DTO,選擇需要的參數。而不是使用實體類(會顯示大量不必要的參數)
  • 參數需要進行校驗

    • 實體類/DTO中使用SpringMVC的參數校驗規則(如:@NotBlank、@NotNull等),接口參數前添加@Validated注解
    • 基本數據類型,如有需要在業務中進行參數校驗
  • 參數類型統一使用application/json,前端使用qs進行全局統一攔截解析。不强制使用@RequestParam,如果qs解析沒有問題,不强制使用@RequestBody

4.接口響應數據/狀態碼規範

4.1響應數據結構

[
    "code":"",
    "message":"",
    "data":""
]

相應數據說明:

  • code 為自定義業務狀態碼

  • message 為詳細響應信息

  • data 為響應數據

4.2Http狀態碼使用

狀態碼(status) 說明 備注
200 正常
401 未登錄
403 權限不足
404 訪問資源不存在
500 不可控的服務器异常 可控制的業務邏輯异常使用code代錶

4.3自定義code的使用(自定義狀態碼暫定,需完善和確定

自定義code 說明 備注
0 正常 無特殊含義
401 未登錄 通用遵從http
403 權限不足,認證失敗 通用遵從http
404 訪問資源不存在 通用遵從http
500 不可控的服務器异常 通用遵從http
1xxx 通用業務狀態 以1開頭代錶通用業務狀態
2xxx 具體項目中的業務定義狀態 以2開頭代錶具體項目中的業務定義狀態
3xxx 第三方依賴狀態,如微信等 以3開頭代錶第三方依賴狀態

例如:


	/** * 成功(默認返回狀態碼) */
    SUCCESS(0, "SUCCESS"),

    /** * 全局未知异常 */
    SEVER_ERROR(500, "服務器异常,請重試"),

    /** * 請求失敗(一般前端處理,不常用) */
    BAD_REQUEST(400, "請求失敗"),

    /** * 請求資源不存在(靜態資源不存在,不常用) */
    DATA_NOT_FOUND(404, "沒有數據了"),

    /* * 登錄、權限認證异常 */
    LOGIN_EXPIRE(401, "未登錄"),
    IDENTITY_NOT_POW(403, "您的用戶權限不足"),


    /* ====通用异常==== */

    /* 1001-1010 通用操作相關 */
    OPERATION_FAIL(1001, "操作失敗!"),
    SELECT_OPERATION_FAIL(1002, "查詢操作失敗!"),
    UPDATE_OPERATION_FAIL(1003, "更新操作失敗!"),
    DELETE_OPERATION_FAIL(1004, "删除操作失敗!"),
    INSERT_OPERATION_FAIL(1005, "新增操作失敗!"),

    /* 1011-1050 登錄注册相關 */
    LOGIN_FAIL(1011, "登錄失敗,賬號或者密碼錯誤"),
    LOGIN_FAIL_RELOGIN(1012, "登錄失敗,請重試"),
    LOGIN_FAIL_CODE(1013, "驗證碼錯誤"),
    NO_USER(1014, "用戶不存在"),
    REGISTER_FAIL(1015, "注册失敗,手機號已經存在"),
    NO_USER_PHONE(1016, "認證失敗,手機號不存在"),
    PARAMS_NOT_NULL(1017, "請求參數不能為空"),

    /* 1051-1070 短信業務相關 */
    SMS_NOT_SEND(1051, "短信發送失敗"),
    SMS_CODE_EXPIRE(1052, "短信驗證碼失效"),
    SMS_CODE_VERITY_FAIL(1053, "短信驗證碼驗證失敗"),

    /* 1071-1100 文件、資源相關 */
    FILE_OVERSTEP_SIZE(1071, "文件超出規定大小"),
    FILE_UPLOAD_FAIL(1072, "文件上傳失敗"),
    FILE_LOADING_FAIL(1073, "文件不存在,加載失敗"),
    FILE_REQUEST_FAIL(1074, "文件類型不支持查看"),
    FILE_TYPE_IMAGE_FAIL(1075, "請上傳圖片類型的文件"),

    /* 1101-1199 請求參數相關 */
    PARAM_IS_INVALID(1101, "參數無效"),
    PARAM_IS_BLANK(1102, "參數為空"),
    PARAM_TYPE_BIND_ERROR(1003, "參數類型錯誤"),
    PARAM_NOT_COMPLETE(1004, "參數缺失"),

    /* -----------平安科院 業務相關(2xxx)------------ */
    PAKY_VISITED_NOT_EXIT(2024, "被訪人不存在"),
    APPOINTMENT_NOT_FIND(2100, "預約id不存在"),
    VISITOR_VALUE_FORMAT(2101, "訪客鏈接value格式不對"),
    APPOINTMENT_QUERY_TIME_ERROR(2102, "查詢時間有誤"),
    APPOINTMENT_TIME_OUT(2103, "預約時間過期,自動簽為過期"),
    REIDS_ADD(2200, "redis 服務添加异常"),
    REIDS_GET(2201, "redis 服務無此信息"),
    USER_ROLE_ERROR(2204, "用戶角色异常"),
    NO_ROLE(2203, "無此角色id"),
    HIK_ADD_ORDER(2202, "海康 添加失敗"),

    /* 第三方相關(3xxx) */
    /* 3001-3020 微信公眾號 */
    WX_GZH_ACCESS_TOKEN_FAIL(3001, "微信公眾號JSSDK獲取access_token失敗"),
    WX_GZH_JS_API_TICKET_FAIL(3002, "微信公眾號JSSDK獲取jsapi_ticket失敗"),
    WX_GZH_SIGN_FAIL(3003, "微信公眾號JSSDK獲取SIGN失敗"),
    WX_CODE_EMPTY(3004, "微信wxCode為空"),
    WX_CODE_OUTTIME(3005, "微信wxCode失效或不正確請重新獲取"),


4.4如何使用Http狀態碼和自定義code

  • 在出現Http狀態碼使用的情况時,推薦使用Http狀態碼,錶述業務狀態。自定義code如果沒有特殊含義,同時遵循http狀態(200除外)。
  • 業務狀態碼統一使用自定義code錶述,http狀態碼使用200

5.接口訪問權限

  • 開發階段接口不明確其訪問權限,將接口設置為匿名接口。即接口添加注解@AnonymousAccess
  • 在得知接口的訪問權限時,添加權限注解——@PreAuthorize("@permissions.check('admin')")
  • 項目測試/上線前,審查所有接口的訪問權限是否對應。尤其是去掉不必要的匿名接口標識@AnonymousAccess

二、异常處理規範

1.使用异常處理的方式(暫定)

throw new BadRequestException(String msg);
throw new BadRequestException(HttpStatus status,String msg);

2.什麼是使用异常處理?

接口業務邏輯,有出錯的風險的都建議進行异常處理。比如查詢返回集合數據為空,异常的入參方式…

總的來說,只要有出錯風險或者是不符合要求的情况下,提前做好業務的异常處理

三、事務規範

1.什麼時候使用事務?

  • 只要有多條(大於等於2條)對數據庫增删改操作的接口强制添加數據庫事務處理
  • 事務控制在Service層的方法添加@Transactional(rollbackFor = Exception.class)
    • MybatisPlus如果直接使用service的數據庫操作方法,在controller也需要添加@Transactional(rollbackFor = Exception.class)

四、日志規範

1.什麼時候使用日志?

  • 一般在使用异常處理的使用,同時記錄日志
    • 日志級別warn/error
  • 在進行接口操作(業務處理)時使用日志記錄
    • info/warn

2.如何使用日志記錄?

  • 使用lombok提供的快速日志操作。在類上添加@Slfj注解,在業務中直接使用log.info/warn/error(“記錄日志”)

  • 日志記錄格式:log.日志級別("【業務名】詳細業務操作信息"),例如:

    log.info("【修改用戶】userId:" + userId);
    log.error("【修改用戶失敗】userId:" + userId);
    

3.日志文件生成

  • 日志文件在項目根目錄下生成,跟項目走,以logs命名
  • 以每天每小時生成一個日志文件命名為——server.log.%d{yyyy-MM-dd-HH}

五、文件夾結構規範

1.在指定的package下開發,業務邏輯代碼一般放在system模塊的modules下

2.common模塊盡量封裝在任何項目,任何模塊都有可能使用的通用方法和工具類。

  • 如果代碼在不同的項目/模塊可能不一樣,盡量不要封裝在common模塊中

3.文件夾結構

-common 通用模塊
-system 核心業務模塊
-tool 第三方工具模塊

4.通用文件夾結構

-modules
--業務模塊名
---api
----controller
----service
-----impl(service實現類的包)
----mapper(mybatis統一使用)/dao
----entity(統一使用)/domain
----bo
----vo
----dto
-config
-utils

六、Mybatis/MybatisPlus規範

1.聯錶查詢使用注解

2.條件構造器的使用

  • 在使用條件構造器Wrapper時,强烈推薦使用其Lambda語法(這樣使用的好處是,不用以數據庫字段為條件,而是以JavaBean的getter、setter方法為條件,與數據庫解耦,增强其可讀性和可維護性
    • Lambda語法使用方式一:使用LambdaQueryWrapper、LambdaUpdateWrapper,直接使用Lambda語法
    • Lambda語法使用方式二:使用QueryWrapper、UpdateWrapper的lambda()方法,使用其Lambda語法

3.自定義屬性注入

  • 使用自定義屬性注入維護createTime、updateTime、createBy、updateBy等,需要注意在使用MybatisPlus提供的方法會維護,但是使用注解手擼sql時並不能維護。所以在使用注解手寫sql時,不要忘記了維護createTime、updateTime、createBy、updateBy等數據

4.邏輯删除

  • 邏輯删除字段在yml文件中配置,數據庫統一好邏輯删除字段,推薦使用is_deleted(不能使用is_delete,轉Javabean去掉is,delete為mysql關鍵字)
  • 邏輯删除推薦使用0為未删除,1為邏輯删除,並且數據庫設置默認值為0
  • 手寫sql,即在mapper類中寫的sql語句,在做SELECTUPDATE操作時需要維護is_deleted
  • 統一使用邏輯删除(暫定包括中間錶),所有删除操作,手寫sql全部使用UPDATE,將is_deleted改為1.

5.MybatisPlus代碼生成

  • 代碼生成時間類型默認為Java8數據格式LocalDateTime
  • 代碼生成推薦開放ActiveRecord模式(setActiveRecord(true)),實體類會繼承Model接口
  • 推薦JavaBean支持鏈式操作(setChainModel(true)),並且移除is前綴(setEntityBooleanColumnRemoveIsPrefix(true))

6.業務邏輯寫在service層,還是寫在controller層

因為MybatisPlus支持service直接操作數據庫,而且比mapper層提供的方法更加豐富,所以業務邏輯寫在service層,還是寫在controller層,是個值得考慮的問題。推薦根據以下情况决定,業務邏輯寫在哪裏:

  • 如果業務邏輯比較簡單,只有很少的代碼量,推薦業務邏輯寫在controller層
  • 如果業務邏輯比較複雜,有大量的邏輯判斷和代碼,推薦將業務邏輯寫在service層。並將方法拆分進行封裝,暴露給controller的方法聲明為public,其餘方法聲明為private,只提供給本service類使用
  • 如果需要在mapper層手寫sql,調用其mapper方法,則==强制==使其業務邏輯方法寫在service層

七、Java開發業務規範

1.阿裏巴巴Java開發手册和IDEA阿裏巴巴代碼檢查插件

推薦開發前看阿裏巴巴Java開發手册,並在IDEA中下載阿裏巴巴代碼檢查插件(養成習慣,寫出及規範又優美的代碼)

2.推薦枚舉類enum的使用

  • 數據庫tinyint類型數據的判斷,在Java中推薦封裝枚舉類進行判斷
  • 業務邏輯if判斷,如果判斷條件比較多,推薦使用枚舉類判斷

3.文件上傳/下載規範

  • 文件上傳比特置跟項目走,在項目根目錄下建立upload文件夾
  • 文件命名推薦添加uuid作為內容之一,防止文件命名重複導致异常
  • 文件、上傳都要走安全框架,需要做權限控制
    • 文件瀏覽/下載不能直接訪問,需要走接口,進行權限控制

4.工具類封裝

  • 工具類比特置,推薦封裝在utils下
    • 通用工具類封裝在common模塊下
    • 和某個模塊相關業務的工具類,封裝在相關模塊下
  • 工具類推薦封裝成static靜態方法(有的不能不强求,比如需要bean注册)

5.配置類

  • 配置類比特置,推薦封裝在config下

    • 通用配置類封裝在common模塊下
    • 和某個模塊相關業務的配置類,封裝在相關模塊下
  • 配置類使用配置方式

    • 推薦使用Java配置類

    • 不推薦使用xml配置(日志配置除外)

    • 推薦配置參數寫在yml中進行讀取

      • 大量的配置讀取,推薦寫Properties類。可以省去大量屬性的@Value讀取
      @Data
      @Configuration  //錶示為配置類,注册到spring bean容器中
      @ConfigurationProperties(prefix = "jwt") //讀取的yml配置的公共前綴
      public class SecurityProperties {
              
      
      }
      

6.SpringBoot

  • SpringBoot推薦使用2.1.0.RELEASE版本,多次使用穩定版本,暫未發現异常

  • AppRun推薦放置在根包下,一般要進行各種掃描,如果不這樣防止,可能會出現掃描不到的錯誤(主要由@SpringBootApplication注解引起)

  • 推薦配置類使用yml文件,更好的層級結構

  • 推薦配置開發環境、測試環境、生成環境的配置文件。在不同環境下使用不同的配置文件

    image-20200912220158381

7.注釋規範

  • 所有class、interface、enum等强制在類頭部加注釋

    • 注釋方式:javadoc注釋

    • 注釋內容

      • 功能描述(description)
      • 作者(@author)
      • 日期(@Date)
    • 注釋模板

      /** * description:對返回前端數據進行封裝 * * @author RenShiWei * Date: 2020/7/9 22:09 **/
      @Data
      public class ResponseResult<T> {
              
          
      }
      
  • 所有成員變量,推薦添加注釋

    • 注釋方式:javadoc注釋

    • 注釋模板

      /**
      * 方式一:
      * 狀態碼
      */
      private Integer code;
      
      /** 方式二:狀態信息說明 */
      private String message;
      
  • 所有方法,强制添加注釋

    • 注釋內容:

      • 功能描述(description)
      • 參數信息(@param)
      • 返回值信息(@return)
      • 作者(@author)(推薦,可知道方法誰寫的,方便維護)
      • 日期(@Date)(推薦,可知道方法大致是在什麼時候寫的)
    • 注釋模板

      /** * description: 接口調用成功,返回枚舉中自定義的狀態碼及數據 * * @param responseEnum 自定義枚舉 狀態碼和信息 * @param data 返回數據 * @return 枚舉中自定義的狀態碼及數據 * @author RenShiWei * Date: 2020/7/10 19:57 */
      public static <E> ResponseResult<E> ok ( ResponseEnum responseEnum, E data ) {
              
          return new ResponseResult<>(responseEnum, data);
      }
      
  • swagger注釋(一般在controller),如果有swagger,可不寫javadoc注釋

    • 注釋內容

      • 參數
    • 注釋模板

      /** * 根據主鍵id查詢一條部門錶信息 * * @param id 部門錶ID * @return 部門錶信息 * @author RenShiWei * @since 2020-08-06 */
      @GetMapping("/{id}")
      @ApiOperation(value = "查詢一條部門錶信息", notes = "根據主鍵id查詢 \n author:RenShiWei")
      @ApiImplicitParam(name = "id", value = "部門錶id", paramType = "path")
      public ResponseResult<Dept> deptFindById ( @PathVariable Long id ) {
              
          Dept dept = iDeptService.getById(id);
          if (ObjectUtil.isNull(dept)) {
              
              log.error("【查看部門錶失敗");
              return ResponseResult.ok(ResponseEnum.DATA_NOT_FOUND);
          }
          return ResponseResult.ok(dept);
      }
      
    • 注釋規範

      • 如果路徑中有==“/{id}”類似這樣的參數,並且在參數前使用@PathVariable注解,那麼在swagger中@ApiImplicitParam,需要將paramType設置為"path"==。
      • 參數都必須加@ApiImplicitParam注解,包含name和value,paramType選填
      • 接口方法加@ApiOperation注解,包含value和notes。note寫上作者信息,方便在swagger中得知接口是誰寫的
  • 業務注釋

    • 業務中多寫注釋,方便開發和維護,養成良好習慣
    • 一塊業務使用塊級注釋
    • 一行代碼使用行級注釋

八、第三方依賴規範

1.第三方依賴的引入規範

  • 强制不推薦隨意引入第三方依賴。引入依賴前需要經過對比和調研,並且知曉其優缺點
  • 同一項技術,强烈建議統一使用同一項技術。保持規範和一致,提高代碼的可讀性和可維護性;同時减少依賴的引入,降低項目的冗餘。
  • 引入第三方依賴,推薦引入其穩定版本。防止第三方依賴出現未知异常。大多數時候,最新版本,並不一定是最好的。

2.Java工具包推薦使用依賴

  • Java第三方工具包推薦使用——hutool。輕量級,基本涵蓋Java開發80%以上的工具類。官方文檔https://hutool.cn/docs/#/
  • JSON序列化也推薦使用hutool下的json處理

九、Maven規範

1.pom文件規範

  • SpingBoot提前規定好父版本

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.0.RELEASE</version>
    </parent>
    
  • jar引入規範

    • jar包版本統一在下定義,使用時${lombok.version}。方便統一管理所有jar包版本
    • 下定義<project.build.sourceEncoding>和<project.reporting.outputEncoding>為UTF-8;<java.version>為1.8
    • 如果是分模塊開發在父工程的pom文件中先使用鎖定jar包版本,在需要的時候引入jar包。防止jar包在不需要的模塊中引入,造成冗餘。
      • 如果不想某個引來會發生依賴傳遞,設置當前依賴true
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <hutool.version>5.2.5</hutool.version>
        <lombok.version>1.18.8</lombok.version>
    </properties>
    
    	<!-- 鎖定jar包版本 -->
        <dependencyManagement>
            <dependencies>
                <!--    hutool的java開發工具包    -->
                <dependency>
                    <groupId>cn.hutool</groupId>
                    <artifactId>hutool-all</artifactId>
                    <version>${
          hutool.version}</version>
                </dependency>
    
                <!--lombok插件-->
                <dependency>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
                    <version>${
          lombok.version}</version>
                    <optional>true</optional>
                </dependency>
             </dependencies>
        </dependencyManagement>
    
  • 在要打jar的模塊下添加如下插件(最好不要在父工程添加,可能造成打包异常)

    <build>
        <plugins>
        	<!-- spring-boot插件 -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <jvmArguments>-Dfile.encoding=UTF-8</jvmArguments>
                </configuration>
            </plugin>
            <!-- 跳過單元測試 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <skipTests>true</skipTests>
                </configuration>
            </plugin>
        </plugins>
    </build>
    

十、Java數據對象使用規範

1.各種對象的定義

1.1PO(Persistant Object) 持久對象

  • 在 o/r 映射的時候出現的概念,如果沒有 o/r 映射,沒有這個概念存在了。通常對應數據模型 ( 數據庫 ), 本身還有部分業務邏輯的處理。可以看成是與數據庫中的錶相映射的 java 對象。
  • 最簡單的 PO 就是對應數據庫中某個錶中的一條記錄,多個記錄可以用 PO 的集合。 PO 中應該不包含任何對數據庫的操作。
  • 一般/暫時不使用

1.2DO(Domain Object)領域對象

  • 從現實世界中抽象出來的有形或無形的業務實體。一般和數據中的錶結構對應。
  • Java實體類與數據庫對應,一般放在entity/domain包下
  • 常用

1.3TO(Transfer Object) ,數據傳輸對象

  • 在應用程序不同 tie( 關系 ) 之間傳輸的對象
  • 一般/暫時不使用

1.4DTO(Data Transfer Object)數據傳輸對象

  • 這個概念來源於J2EE的設計模式,原來的目的是為了EJB的分布式應用提供粗粒度的數據實體,以减少分布式調用的次數,從而提高分布式調用的性能和降低網絡負載,但在這裏,我泛指用於展示層與服務層之間的數據傳輸對象。
  • 數據傳輸對象:xxxDTO,xxx 為業務領域相關的名稱
  • 常用

1.5VO(view object) 值對象

  • 視圖對象,用於展示層,它的作用是把某個指定頁面(或組件)的所有數據封裝起來。
  • 展示對象:xxxVO,xxx 一般為網頁名稱
  • 少用

1.6BO(business object) 業務對象

  • 從業務模型的角度看 , 見 UML 元件領域模型中的領域對象。封裝業務邏輯的 java 對象 , 通過調用 DAO 方法 , 結合 PO,VO 進行業務操作。 business object: 業務對象 主要作用是把業務邏輯封裝為一個對象。這個對象可以包括一個或多個其它的對象。 比如一個簡曆,有教育經曆、工作經曆、社會關系等等。 我們可以把教育經曆對應一個 PO ,工作經曆對應一個 PO ,社會關系對應一個 PO 。 建立一個對應簡曆的 BO 對象處理簡曆,每個 BO 包含這些 PO 。 這樣處理業務邏輯時,我們就可以針對 BO 去處理。
  • 使用場景
    • 主要用於一對一、一對多、多對多關系的實現,在dao/mapper層查詢數據庫數據返回給前端
  • 常用

1.7DAO(data access object) 數據訪問對象

  • 是一個 sun 的一個標准 j2ee 設計模式, 這個模式中有個接口就是 DAO ,它負持久層的操作。為業務層提供接口。此對象用於訪問數據庫。通常和 PO 結合使用, DAO 中包含了各種數據庫的操作方法。通過它的方法 , 結合 PO 對數據庫進行相關的操作。夾在業務邏輯與數據庫資源中間。配合 VO, 提供數據庫的 CRUD 操作
  • 使用場景
    • 在使用mybatis技術時,暫不使用,常用mapper
  • 在使用mybatis時,一般不使用

1.8POJO(plain ordinary java object)

  • 是 DO/DTO/BO/VO等 的統稱,禁止命名成 xxxPOJO

2.各種對象使用的注意事項

2.1常用的數據對象:

DO、BO、DTO

2.2.JavaBean對象的文件夾結構

與entity平級,詳情參看文件夾結構規範

十一、基本數據類型與包裝數據類型規範

  • POJO類屬性的數據類型强制使用包裝數據類型
  • 方法形參、方法返回值推薦統一使用包裝數據類型
  • 方法體基本數據類型與包裝數據類型都可使用,視具體情况定

MySQL規範

一、用戶及權限規範

1.mysql用戶命名規範

  • 賬號名根據項目數據庫命名(可取其簡寫)
  • 密碼數據庫名[email protected]年份

以新生報名系統為例:

數據庫:electronic_registration
賬號:elec_reg
密碼:ElecReg@2020

2.數據庫權限

  • select
  • insert
  • delete
  • update
  • create
  • index(索引權限)

3.執行語句

# 創建用戶可以在任意主機登錄,(@'%'代錶任意主機)
create user 'elec_reg' @'%' identified by '[email protected]';

# 授予用戶權限,(@'%'代錶任意主機,electronic_registration.*代錶electronic_registration數據庫下所有的錶都具有這樣的權限)
grant select,insert,delete,update,create,index on electronic_registration.* to elec_reg @'%';

前端規範

一、文件夾結構規範

1.Vue-cli項目文件夾結構

-node_modules		依賴安裝文件夾(要進行git忽略)
-dist				build後的文件夾(要進行git忽略)
-public 			主要放置入口index.html文件和項目LOGO
-src
--api 				**請求api封裝(封裝請求-常用)
--assets			靜態資源
--components		**自定義組件封裝(封裝所需要的組件-常用)
--router			**路由(路由跳轉-常用)
--store				vuex配置
--utils				通用工具封裝
--views				**頁面開發(主要的頁面開發-常用)
-App.vue			vue根頁面
-main.js			vue全局配置
-settings.js		項目配置
-.env.development	開發環境配置
-.env.production	生產環境配置
-package.json		依賴配置
-vue.config.js      vue項目環境配置文件

標記“******”,代錶日常業務開發經常使用的目錄

命名規範

一、Java命名規範

1.Java常用命名

  • class、interface、enum使用大駝峰,例如:“WxUser”
  • interface命名以“I”為前綴,代錶接口,例如:“IUserService”
    • 接口實現類命名統一使用後綴impl,例如:”UserImpl“
  • 包命名使用全小寫
  • 變量、方法、參數名等使用小駝峰,例如:“getUserInfo”
  • 常量統一使用大寫,不同單詞間使用“_”連接,例如:“MAX_VALUE”
  • JavaBean命名,統一後綴使用大寫。例如:“UserInfoBO、PageVO、UserDTO”等。
  • MVC各層命名示例
    • entity——User
    • mapper/dao——UserMapper/UserDao
    • service——IUserService
      • 實現類——UserServiceImpl
    • controller——UserController

二、HTML/CSS命名

  • 統一使用小寫,單詞間使用“-“連接。例如:”user-p“
  • 自定義標簽强制統一使用“-”連接,不能出現單一單詞,區別html標簽。例如:“icon-select”

三、MySQL命名

1.用戶及密碼

參看:mysql用戶命名規範

環境要求

一、後端Java環境

環境/技術 版本 備注
java 1.8
mysql 8.x 統一使用8.x。特殊情况下也可以使用5.7版本
Springboot 2.x 常用2.1.0.RELEASE版本。比較穩定,暫未非發現問題
hutool 5.x Java開發工具包
MybatisPlus 3.3.x
redis 使用springdata redis 遵從springboot的父版本

上述只是羅列Java後端的主要環境版本,如需引入其他依賴,請引入穩定版本。第三方依賴請參看上文八、第三方依賴規範

二、前端環境

環境/技術 版本 備注
Element UI PC Web組件庫
Vant Mobile H5頁面組件庫
Vant-weapp 微信小程序組件
uniapp 小程序開發框架

團隊協作git規範

一、基本概念/規範

1.主從倉庫的概念

  • 主倉庫(upstream)
    • 所有人不能直接提交(push)代碼到主倉庫,只能提交代碼到從倉庫,然後提PR到主倉庫。由主倉庫管理員審核代碼,决定代碼是否要合進主倉庫。
    • 所有拉取代碼(clone和pull),要對主倉庫進行操作,保證代碼同步。
    • 所有代碼提PR至主倉庫的develop分支
  • 從倉庫(origin)
    • 所有人對從倉庫進行開發,push代碼到從倉庫,然後提PR至主倉庫進行審核。
    • push代碼,最好每個階段(可以以天/業務分)都提交到新的分支,項目結束在删除不必要的分支
      • 方便進行回退,和看曆史代碼

2.倉庫分支

  • 主倉庫分支
    • 所有開發均在develop分支開發
  • 從倉庫分支
    • 每個階段代碼提交到新的分支
    • 分支命名推薦“業務+日期”,例如:env9.13——環境搭建9月13日
      • 方便知道什麼業務,在那天提交的代碼

二、本地分支和遠程分支規範

1.分支名命名

  • 分支名稱建議為:“業務+日期”,例如:env9.13——環境搭建9月13日
    • 方便知道什麼業務,在那天提交的代碼

2.什麼時候新建分支

  • 每天或者每個業務完成階段,建議新建立分支。待項目開發完畢,删除不必要的分支
    • 方便代碼回退
    • 方便查看曆史代碼

三、pull代碼規範

1.什麼時候pull代碼?

  • 每日早上上班開始開發前pull代碼
  • push代碼到從倉庫時,必須先pull主倉庫代碼

2.怎麼pull代碼?

  • 查看git狀態,沒有問題再pull代碼
git status
  • 將本地代碼存進緩存區
git stash save "備注信息"
  • 查看緩存區內容,判斷是否存進緩存區
git stash list
  • pull主倉庫代碼
git pull upstream develop
  • 將緩存區代碼取出merge(git stash pop取出並删除緩存區代碼,只取出為git stash apply
git stash pop
  • 查看git狀態,如果沒有繼續開發
git status

四、commit/push代碼規範

1.pull主倉庫代碼(可能主倉庫代碼出現更新,參看上文pull代碼規範

2.查看git狀態

git status

3.查看這次修改了什麼,那些妥當,那些不妥當,按q可以退出

git diff

4.選擇全部修改的文件(也可以自行選擇)

git add .

5.提交(commit)到本地倉庫

git commit -m "feat:add UserManagement"

6.上傳到遠程從倉庫

  • 這裏的HEAD指當前分支,冒號後面指要push的分支,如果遠程倉庫沒有,會自動在遠程倉庫創建該分支。(雖然HEAD:分支名稱可以省掉,用默認的,但還是建議加上)

  • 分支名稱建議為:“業務+日期”

  • 每天或者每個階段,可以新建一個遠程分支,上傳代碼。方便回退和查看曆史代碼

git push origin HEAD:分支名稱

7.提pr至主倉庫(create request merge),等待主倉庫管理員審核代碼

五、git status使用規範

在執行git敏感操作如git stashgit commitgit push等操作前,强制推薦先使用git status查看當前git狀態是否有問題。

六、拉取(clone)代碼

拉取代碼步驟:

1.添加本機公鑰到gitlab

2.fork主倉庫,生成自己的從倉庫

  • 如果沒有建立主倉庫,請聯系項目負責人

3.clone從倉庫代碼到本地代碼指定比特置(clone操作,推薦使用ssh方式,更加安全可靠)

  • clone代碼

    • 這樣clone會將倉庫所有的分支的代碼都clone下來,然後可以選擇分支開發
    git clone ssh://xxx.git
    
  • clone單分支代碼

    • 很多時候沒必要clone所有分支,而是指定分支去clone
    git clone -b 分支名 ssh://xxx.git
    

4.關聯遠程主倉庫

  • 查看當前關聯遠程倉庫的分支

    git remote -v
    
    • 一般會顯示有兩條記錄(關聯的是遠程從倉庫)
    $ git remote -v
    origin  ssh://[email protected]:8022/aaa/xxx.git (fetch)
    origin  ssh://[email protected]:8022/aaa/xxx.git (push)
    
  • 關聯遠程主倉庫

    $ git remote add upstream ssh://主倉庫地址
    
    $ git remote -v
    origin  ssh://[email protected]:8022/aaa/xxx.git (fetch)   #自己的
    origin  ssh://[email protected]:8022/aaa/xxx.git (push)    #自己的
    upstream        ssh://[email protected]:8022/aaa/xxx.git (fetch)    #項目組長的
    upstream        ssh://[email protected]:8022/aaa/xxx.git (push)     #項目組長的
    

此時拉取倉庫代碼,和初始設置完畢。

七、初始化上傳本地代碼至主倉庫

上述操作說的如何拉取代碼是在主倉庫建立好的前提下,直接拉取,然後進行開發的操作。此時還沒有開發,本地沒有代碼的情况,可使用直接建立主倉庫,拉取(clone)代碼進行開發的情况。

但是如果是你在本地已經寫了很多的代碼,在寫之前還沒有建立主倉庫,或者建立主倉庫,你並沒有關聯主倉庫,或者沒有使用git。那麼上述clone代碼的方式就够用了。總結下來有以下情况:

  • 在本地已經寫了代碼
  • 想要上傳本地代碼並同步到主倉庫

可按照如下方式解决:

方式一:

1.按照上述clone倉庫代碼的方式clone

2.將本地項目的.git文件删除,複制到項目根路徑

3.將項目上傳到從倉庫

4.提PR至主倉庫

方式二:

1.聯系項目負責人建立主倉庫

2.fork主倉庫,生成自己的從倉庫

3.將本地代碼上傳到從倉庫

  • 如果當前本地項目有.git文件夾,删除

  • 右鍵點擊git bush here打開git控制臺

  • 依次執行如下代碼

    #1.初始化git環境,建立.git文件夾
    git init
    
    #2.在gitlab上,將對應的項目從倉庫的克隆/下載地址進行複制(例如:ssh://xxx.git),並執行如下代碼,關聯遠程從倉庫
    git remote add origin ssh://xxx.git
    
    #3.在gitlab上,將對應的項目主倉庫的克隆/下載地址進行複制(例如:ssh://xxx.git),並執行如下代碼,關聯遠程主倉庫
    git remote add upstream ssh://xxx.git
    
    #4.將本地代碼放進git緩存區
    git stash save "備注信息"
    
    #5.查看緩存區內容,判斷是否存進緩存區
    git stash list
    
    #6.更新主倉庫代碼
    git pull upstream develop
    
    #7.將緩存區代碼取出並删除,git stash pop相當於取出並删除,也可分別執行git stash apply和git stash drop [email protected]{$num}
    git stash pop
    
    # 執行到這裏基本已經同步,可以直接將代碼同步到主倉庫,看看是否有問題
    
    #8.選擇當前目錄下所有文件,准備commit
    git add .
    
    #9.commit提交代碼到本地倉庫
    git commit -m "備注信息"
    
    #10.push代碼到從倉庫
    git push origin HEAD:分支名稱
    
    #11.如果push使用强制提交代碼到遠程從倉庫,可將master換成執行分支(最好提前建好分支)
    git push -u origin master -f
    
    #此時可查看gitlab從倉庫上即有對應的本地代碼,然後提PR到主倉庫
    

八、日常開發——早上上班操作

日常開發,每天早上上班執行的操作:

1.切換本地分支。分支名:“業務+日期”,例如:env9.13

git checkout -b env9.13

2.pull主倉庫代碼

參看上文pull代碼規範

3.查看git狀態,如果沒有繼續開發

git status

九、日常開發——晚上下班前操作

日常開發,每天晚上下班執行的操作:

1.pull主倉庫代碼(可能主倉庫代碼出現更新,參看上文pull代碼規範

2.查看git狀態

git status

3.查看這次修改了什麼,那些妥當,那些不妥當,按q可以退出

git diff

4.選擇全部修改的文件(也可以自行選擇)

git add .

5.提交(commit)到本地倉庫

git commit -m "feat:add UserManagement"

6.上傳到遠程從倉庫

  • 這裏的HEAD指當前分支,冒號後面指要push的分支,如果遠程倉庫沒有,會自動在遠程倉庫創建該分支。(雖然HEAD:分支名稱可以省掉,用默認的,但還是建議加上)

  • 分支名稱建議為:“業務+日期”

  • 每天或者每個階段,可以新建一個遠程分支,上傳代碼。方便回退和查看曆史代碼

git push origin HEAD:分支名稱

7.提pr至主倉庫(create request merge),等待主倉庫管理員審核代碼

服務器部署規範

一、docker

服務器運維時,可以使用docker完成的,統一使用docker的方式。

1.docker安裝

參考博客:docker安裝及docker常用命令

2.鏡像(images)

命名

根據所使用的技術+"_"命名。例如鏡像使用centos、git、java8、maven,命名為centos_git_java8_mvn

3.容器

  • 運行容器最好掛載宿主機相應的目錄
  • 運行容器可以設置時區-e TZ="Asia/Shanghai"

二、nginx

1.docker安裝nginx(推薦使用軟連接將conf.d文件夾掛載到宿主機)

參考博客:docker安裝nginx規範所有項目的反向代理(一個項目一個反向代理的conf配置文件)

2.推薦的重啟nginx方式

如果是nginx的docker容器,重啟可以使用docker restart nginx,但是這樣的啟動方式有很大的缺點,如果nginx啟動有問題,不能很清楚的知道問題在哪,而且不能正常訪問nginx。

推薦nginx啟動方式:

  1. 還是先進入容器
  2. 執行nginx -t命令,測試配置文件是否有問題
    下圖這樣,說明沒有問題:
    在這裏插入圖片描述
    如果配置文件問題(尤其是conf.d下的文件),會在這裏顯示异常
  3. 執行nginx -s reload重啟nginx服務
    成功如下圖
    在這裏插入圖片描述
    如果遇到線程問題,啟動失敗,可參看:docker 中使用nginx容器無法正常啟動,報錯signal process started和kili(3255,1) failed (3: No such process)

如果沒有問題,就可以進行訪問測試了

3.nginx統一管理項目的反向代理

  1. 項目下放置 “項目名.conf” 文件方便nginx統一反向代理
  2. 使用軟連接的方式,將項目下的conf文件與nginx的conf.d的文件夾同步

將server配置的conf文件放在conf.d下,nginx運行後會將其添加到nginx.conf文件,從而實現反向代理。(個人推測)。

項目conf文件參考示例:

server {
    
    listen       9021;
    server_name  localhost;
    location / {
    
      root   /var/www/html/項目名/dist;
      index  index.html;
      try_files $uri $uri/ /index.html;
    }
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
    
      root   /usr/share/nginx/html;
    }
}

如果是直接複制進nginx的conf.d文件現在是確實可使用,但是如果項目的conf文件出現改動,那麼並不能與nginx的conf.d的conf文件同步。

可以進入nginx的項目容器,使用軟連接的方式將conf文件與nginx的conf.d目錄關聯,實現同步。具體操作如下:

  • 進入nginx容器,確定項目的conf路徑(例如 /var/www/html/項目名/項目名的conf
  • 項目.conf 關聯進 /nginx_conf/conf.d (這個目錄曾經與 /etc/nginx/conf.d 建立過反向軟連接,即/etc/nginx/conf.d移動到/nginx_conf,/nginx_conf/conf.d建立/etc/nginx的軟連接,否則無法在宿主機操作。詳細參看上文的前提下的nginx配置)
 ln -s /var/www/html/項目名/項目名的conf /nginx_conf/conf.d
  • 建立軟連接後,或者修改conf後需要重啟nginx服務

三、服務器部署前端vue項目

參考博客:docker 構建centos7+git+nvm鏡像,實現自主切換node版本統一部署前端vue項目

四、服務器後端Springboot項目

參考博客:docker 構建git+maven+jdk8的centos7環境,實現輕量級的springboot項目的自動化部署

版權聲明
本文為[胡毛毛_三月]所創,轉載請帶上原文鏈接,感謝
https://cht.chowdera.com/2022/01/202201270044529278.html

隨機推薦