Building application development specifications based on spring boot

1. Significance and role of the norm

• Coding specification maximizes team development collaboration efficiency
• The coding specification reduces the maintenance cost of a software as much as possible, and virtually no software is maintained by the initial developer throughout its lifecycle.
• Coding specifications can improve the readability of the software, allowing developers to quickly and thoroughly understand the new code
• Normative coding can also enable developers to develop good coding habits, and even exercise more rigorous thinking

2. Code Warehouse Specification 2.1 Common components

• Common components are typically Java libraries that provide handler packages for specific problems
• Public Component Warehouse Address: Https://git.netposa.com/java-library-group
• Coordinate naming conventions for public components
  • Group number:<groupid>com.company.library</groudid> Fixed value
  • Component name:<artifactid>name</artifactid> name defined by component name
  • Component version:<version>x.y.z</versio> x.y.z defined based on the actual version of the component

2.2 Service Components

• Service components typically refer to service packages that can be deployed, run, and maintained independently.
• Service Component Warehouse Address: Https://git.netposa.com/vias-microservice-group
• Coordinate naming conventions for application components
  • Group number:<groupid>com.company.server</groudid> Fixed value
  • Component name:<artifactid>name</artifactid> name defined by component name
  • Component version:<version>x.y.z</versio> x.y.z defined based on the actual version of the component

3 Development Environment Specification

• Development environment: jdk1.7+
• Development tools: IntelliJ idea 2017 (install Lombok Plugin)
• Build Tool: maven3.x
• Code Management tools: Git/tortoisegit

4. Project Structure Specification 4.1 Brief introduction

A project corresponds to a warehouse in the code warehouse, and the project structure refers to a project directory structure that is created based on Maven. Common component projects, typically creating a MAVEN common project. A service component project, which typically creates a Maven aggregation project and creates several Maven modules that inherit the Maven aggregation project under the aggregated project directory, together as part of the serviced component project.

4.2 Project Name

• Requirements
  • Names of English names, as warehouses, projects, Project roots, components (common components, service components)
  • Chinese name, description for code warehouse
  • The project name is consistent with the name of the Code warehouse
• Defined
  • The project name is usually determined by the team leader
• Example
  • Chinese name: Human Face Data Warehouse
  • Project English Name: Data-warehouse-face
  • Project directory Name: Data-warehouse-face
  • Project Warehouse Address: Https://git.netposa.com/vias-microservice-group/data-warehouse-face.git
  • Initial version: 1.0.0
  • The example is a service component that determines the Maven coordinate naming of the serviced component based on the information defined above:

<groupId>com.company.server</groupId><artifactId>data-warehouse-face</artifactId><version>1.0.0</version>

4.3 module naming

• Requirements
  • Module Name: {Project name}-{module name} module name concise representation of responsibilities
  • Module name as the name of the module component
• Example
• Data access module of Human face Data Warehouse name: data-warehouse-face-access

4.4 Project Directory

• The project directory follows the MAVEN Conventions directory format

4.5 Source Directory

• Source directory refers to: {Project directory}/src/main/
• Package Definition directory: src/main/assembly
• Code Catalog: Src/main/java
• Resources Catalog: Src/main/resources
  • /DB: Database Script Archive
  • /data: Internally dependent data archiving
• Document Catalog: Src/main/docs
• Script directory: Src/main/bin
  • run-manage.sh Run management scripts (via parameters Start, stop, status, Help info control program run)
  • SH: Service component startup script
  • SH: Service component Stop script

5. Code Specification 5.1 Package Specification

• Project Basic Package: Com.company. {The English name of the project is simplified when it is longer)}. {module name (optional)}
• Config: Configuration class
• Startup: Classes related to service startup
• Client: The related class that provides the clients implementation
• Common: public class, defining a constant class, component
• Entity: Database-related Entities class
• Model: Data Model Class (parametric model, data transfer model, etc.)
• Control: Layer Interface
• Service: Services Tier
• DAO: Database Access Layer

5.2 Log records

• Unified use of the SLF4J interface

5.3 Exception Handling

• Run-time Exceptions: avoid or throw run-time exceptions by means of parameter checks, log records
• Check for exceptions: Check for exceptions need to be captured, processed, logged

5.4 Interface Definitions

• Principle
  • The interface address definition indicates the intent
  • Interface address definition clear, concise, no ambiguity
  • The interface definition of the same service component has consistency
• Format
  • Top-level address format of the control class:/{top class name}, for example:/library the top-level address of the related interface of the staff library
  • Interface Definition API Note description using Swagger
  • Callout Complete Request information, request method, request address, parameter optional, interface description
• Request method
  • GET Url-params
  • POST Form-data
  • POST requestbody (JSON format)
  • POST Mulitpart
• Response mode
  • A unified response model

5.5 Auxiliary Tools

• String processing: Apache Common-lang3
• Time Date Processing: joda-time
• JSON processing: Gson,fastjson
• Collection Extension tool: Guava
• File and Stream processing: Commons-io
• Codec: Commons-codec
• Recommendation: Use open source components whenever possible

5.6 Code comments

• Class, interface, enumeration top-level comments
• Interface Method Comments
• static method comments
• Public method comments
• property field comment for class
• Constant comment
• Not limited to the above

6. Code Control Specification 6.1 Pull principle

• Forced
  • Daily start of work pull
• Conventions
  • Pull before submitting

6.2 Submission Principles

• Forced
  • Commit code must be built successfully (e.g. compile, package into a total)
  • The commit code must be complete (e.g., file less)
  • The commit code must be ignored to the local temporary file (for example: Target, logs,. Idea, *.iml,dist, etc.)
• Conventions
  • Complete a feature submission
  • Modify a bug to modify a commit
  • Resolve Conflict Submission
  • End of work submission daily

6.3 Submit Comments

• Forced
  • Write a comment in Chinese
  • The comments reflect the change of the present submission
• Conventions
  • Add a prefix to the comment description, prefixed by the following
  • [Create] is typically used when a project is created
  • New
  • Modify
  • Delete
  • [Fix-number] fix bug use, number is bug No.

7. Build Specification 7.1 Common Component Building specification

• Building the output component package
• Building the output component source package
• Build publish to company private warehouse

7.2 Building Specifications for service components

• Service component Package naming: {component name}-{version number}-bin.zip
• Build the dist/{component name}-{YYYYMMDDHH} directory to output to the project root directory

Building application development specifications based on spring boot