eliteforge-java-fe-consensus-spec

EliteForge Java Frontend-Backend Consensus Specification

§0 Objective

Used for interface design, interface review, Controller/client implementation, and integration issue diagnosis. Once this skill is triggered, the following rules are mandatory constraints and must not be downgraded to suggestions. If rules conflict, communicate promptly to confirm.

§1 Usage

• When designing an interface, first determine the HTTP method, URL, Param, VO, status code, error code, response body, pagination, and internationalization contract, then write the code.
• When reviewing an interface, point out violations item by item according to this document, and indicate the section number.

§2 Development Consensus

§2.1 Serialization

• The backend uniformly uses Jackson for serialization and deserialization; fastjson is prohibited.
• Java manual serialization uses cn.cisdigital.elite.forge.infra.commons.util.JsonUtils。
• Java uses a global unified ObjectMapper：cn.cisdigital.elite.forge.infra.commons.serialize.ObjectMapperHolder。

§2.1.1 Time Fields

• Use millisecond timestamps for interaction.
• The frontend formats and displays them according to business needs and time zone.

§2.1.2 Enum Fields

• Frontend-backend interaction, database storage, and manual serialization and deserialization all use enum CODE.
• The use of enum name is prohibited. Example:FEMALE(0)、MALE(1) The interaction value uses 0、1, not FEMALE、MALE。

§2.1.3 Long Fields

• The Long type uses string interaction to prevent JS precision loss, such as snowflake IDs.
• /api/** and /inner-api/** 's ObjectMapper uniformly serialize Long as String.
• /open-api/** uses a different ObjectMapper; open interfaces must not handle Long-to-String conversion.

§2.1.4 Field with No Data

• JSON must not omit fields with no data.
• The backend uses null to represent "does not exist".
• The frontend must be compatible with null。

§2.2 Request Method

• Only GET and POST are allowed.
• Restful style is prohibited.

§2.3 Request URL

• URL words use kebab-case, for example /get-unique-data。
• Path parameters are prohibited, for example /my/api/123/detail。

§2.4 Request Content

• Each request uses an independent Param class; cross-interface reuse is prohibited.
• Param classes should not inherit unless necessary.
• Param classes must not contain redundant or useless fields.
• GET requests must not pass List.
• More than three parameters must use POST Request Body.
• The Request Body size must be controlled, and limits of Spring, Tomcat, Nginx, etc. must also be considered.
• Pagination request parameters are uniformly current、size。

§2.5 Response Content

• Each interface has an independent VO class; VO classes of other interfaces must not be reused.
• VO classes should not inherit unless necessary.
• VO classes must not contain redundant or useless fields.
• Only when the interface call succeeds is the HTTP status code 200.
• Service success and failure are represented by different error codes, and error codes must comply with the service status code specification.
• 0 represents a successful request.
• -1 represents a system exception or unknown exception.
• In other cases, return a 9-digit error code: digits 1-3 are the unique product identifier, digits 4-6 are the unique service identifier, and digits 7-9 are the project-defined numeric value; project-defined numeric values must not be repeated, increment starting from 1, and pad leading zeros.
• The unified response body must be code、message、data。
• For list responses, the data is an array; for single-object responses, the data is an object; for paginated responses, the data contains current、size、total、records。

List response:

{
  "code": "服务状态码",
  "message": "响应消息",
  "data": []
}

Single-object response:

{
  "code": "服务状态码",
  "message": "响应消息",
  "data": {}
}

Paginated response:

{
  "code": "服务状态码",
  "message": "响应消息",
  "data": {
    "current": "当前页",
    "size": "显示条数",
    "total": "总数",
    "records": []
  }
}

§2.6 Internationalization

• Use the standard Accept-Language Header to switch languages.
• The Header value format is <语言代码>-<国家或地区代码>, using hyphens, for example zh-CN、en-US。

Output constraints

• When designing or reviewing interfaces, this specification must be explicitly applied, and the section number must be indicated.
• For clauses of the "prohibited" and "must" types, give a clear conclusion, and do not use weakening wording such as "it is suggested that ... may".
• Do not extend the unified response body fields on your own; place business extensions in data。
• For scenarios not covered by the specification, mark them as "requires user supplementation or external confirmation".