eliteforge-be-fe-consensus-spec

EliteForge Frontend-Backend Consensus Specification

Objectives

This skill is converted from the online document "Frontend-Backend Consensus" v1. It is used for interface design, interface review, Controller/client implementation, and integration issue diagnosis. When this skill is triggered, the following rules are mandatory constraints and must not be downgraded to suggestions. If the user requests the latest specification or disputes the rules, verify against the source page:https://dev-platform.cisdigital.cn/elite-forge/code-specification/be-fe/v1/。

How to Use

• When designing an interface, first determine the HTTP method, URL, Param, VO, status code, error code, response body, pagination, and internationalization contracts, then write the code.
• When reviewing an interface, point out violations item by item according to this document, and note the section number.
• When implementing in Java code, you may use both eliteforge-java-coding-spec and eliteforge-framework-specification; non-Java backends must also comply with the protocol-layer rules.

§1 Collaboration Consensus

• Use the Torna interface management platform.
• Use a unified GIT branch management model.
• The backend provides interfaces in a timely manner, and the frontend writes the implementation only after confirming they are correct.
• Core logic must be self-tested before being deployed to the dev environment for integration.

§2 Development Consensus

§2.1 Serialization

• The backend uniformly uses Jackson for serialization and deserialization; fastjson is prohibited.
• For manual serialization in Java, use cn.cisdigital.elite.forge.infra.commons.util.JsonUtils。
• Java uses a globally 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 requirements and time zone.

§2.1.2 Enum Fields

• Frontend-backend interaction, database storage, manual serialization, and deserialization all use the enum CODE.
• The 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/** the ObjectMapper uniformly serializes Long as String.
• /open-api/** uses a different ObjectMapper; open interfaces must not handle Long-to-String conversion.

§2.1.4 Fields with No Data

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

§2.2 Request Methods

• Only GET and POST are allowed.
• The 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.
• Three or more parameters must use POST Request Body.
• The Request Body size must be controlled, and attention must also be paid to limits of Spring, Tomcat, Nginx, etc.
• Pagination request parameters are uniformly current、size。

§2.5 Response Content

• Each API has an independent VO class, and VOs of other APIs must not be reused.
• VO classes must not be inherited unless necessary.
• Redundant or useless fields are prohibited in VO classes.
• The HTTP status code is 200 only when the API call succeeds.
• 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 duplicated, start from 1 and increment, with leading zeros padded.
• The unified response body must be code、message、data。
• For list responses, data is an array; for single-object responses, data is an object; for paginated responses, 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 APIs, this specification must be explicitly applied, and the section number must be indicated.
• Give clear conclusions for clauses of the "prohibited" and "must" types, and do not use weakening wording such as "it is suggested that it may".
• Do not extend the fields of the unified response body on your own; put business extensions in data。
• For scenarios not covered by the specification, mark them as "requires user supplementation or external confirmation".