Front‑Back End Collaboration Guidelines and Best Practices

1. Introduction

Are you struggling to define front‑back end collaboration standards? This guide shares the practices our team has refined and applied for years, helping you confidently reject unreasonable backend designs.

2. Why a Collaboration Standard Is Needed?

With the rise of front‑back end separation, the two sides often drift apart: front‑end focuses on interaction and visual experience, while back‑end emphasizes high concurrency, performance, and scalability. This creates a "gap" where each side does not understand the other's data or rendering logic.

A clear collaboration standard bridges this gap, fostering mutual understanding, improving development efficiency, and reducing communication costs.

3. Collaboration Process Standard

The typical workflow in our team is illustrated below:

Requirement import and UI/visual analysis – product, front‑end, back‑end, testing, and UED align on the understanding of requirements.

Interface design and front‑back end hand‑off – back‑end provides the API, and both sides agree on field definitions.

Technical solution review – ensure requirement comprehension and field feasibility before development.

Parallel development & front‑end mock data – front‑end can mock data for page rendering.

Development environment integration – after self‑testing, perform API integration in the dev environment.

4. How to Define API Standards?

Pre‑agreement: Before defining URL and parameters, front‑end and back‑end must reach consensus.

API comments must be clear: module, enum, required/optional, and whether output can be null.

APIs should be backward compatible; if not, evaluate impact and notify stakeholders.

Changes in API documentation must be promptly synchronized to front‑end.

Back‑end must ensure that defined parameters can be called successfully and function stably.

Metric unit conventions:

Time: use 13‑digit timestamp.

Amount: use cents (integer), adjustable per business.

Request URL & method:

POST APIs must not use GET for parameters.

POST APIs must use application/json format.

API names should be semantic and distinct.

Request parameters:

Maintain consistent naming for fields with the same meaning within a domain.

Business IDs must be strings (JS number precision limits).

Same page different tabs should share consistent APIs.

Response parameters:

Standardize response format.

Avoid vague error messages like "server internal error"; in non‑production, include stack traces for debugging.

List‑type responses should return an empty array [] or empty object {} instead of null.

Only return fields required by the page to avoid unnecessary data.

Enum values should provide both Chinese and English descriptions.

5. Bad Cases in Collaboration

Case 1: Excessive front‑end conditional logic

// Button text & visibility logic
{((record.state === 'RESULT_CONFIRM' && isCurrentUserCreate) || (record.state === 'RESULT_CHECK' && isCurrentUserCreate && currentUserCanCheck)) &&
Confirm
}

['DREFT','AUDIT_FAILD','REVOKE'].includes(record.state) && isCurrentUserCreate &&
Edit
if (id) {
  this.operation = '修改';
  const res = await this.fetchInfo(id);
  ...
} else if (source) {
  const res = await this.fetchSourceInfo(id: source);
  ...
} else {
  const res = await this.fetchBasicInfo();
  ...
}

Solution: Move most display logic to back‑end; front‑end should only handle simple cases (e.g., less than two conditions).

// Back‑end returns an array of button configs
[
  { name: '确认', type: 'resultConfirm' },
  { name: '修改', type: 'edit' }
]

Case 2: Over‑processing data on the front‑end

Multiple APIs are combined on the front‑end to render a single table.

Solution: Back‑end should provide consolidated data; avoid front‑end re‑assembly. For tree data, return full data when size is small; otherwise use async loading with proper pagination.

Case 3: Front‑end maintains enum or dropdown values

// Status mapping in front‑end
const getStatusName = (status) => {
  switch(status) {
    case 0: return '草稿';
    case 1: return '待部门审批';
    case 2: return '待财务审核';
    // ...
    default: break;
  }
}

Solution: Let back‑end supply enum data; front‑end consumes it directly.

// Back‑end returns dropdown options
{
  result: [{ code: string, name: string }]
}

Case 4: PC data structure unsuitable for App

App requires different layout; using PC API forces extra front‑end handling.

Solution: Assess front‑end workload and provide dedicated App APIs when needed.

Case 5: Inconsistent field naming within the same domain

Examples: response.data vs response.result , various time field names, and differing ID field names.

Solution: Maintain a shared field dictionary between front‑end and back‑end.

Case 6: Front‑end calculates monetary ratios and submits them

Solution: For values that need to be stored, let back‑end perform the calculation; front‑end may compute display‑only values.

Case 7: Front‑end maintains business configuration code

Complex validation rules are hard‑coded in the front‑end.

Solution: Provide a generic validation API; front‑end sends data and receives a pass/fail result.

// Request example
{
  code: '99900', // region code
  identity: '11111', // identifier
  datas: [
    { key: 'catalog', value: 'A07' },
    { key: 'assetApproval', value: 0 }
  ]
}

// Response example
{ result: true }

Case 8: Front‑end directly calls another business line’s API

Cross‑line API calls increase coupling and maintenance cost.

Solution: Each business line should provide its own integrated API; avoid cross‑line calls unless absolutely necessary.

Case 9: Inconsistent pagination response formats

// Form 1
{ result: { data: [], total: 0 } }

// Form 2
{ result: { data: [], pagination: { total: 0, pageSize: 10, pageNo: 1 } } }

// Form 3 (recommended)
{ result: { data: [], total: 0, pageSize: 10, pageNo: 1 } }

Solution: Standardize on the third format.

Case 10: Multiple validation APIs for a single form

Three separate validation calls increase front‑end complexity.

Solution: Merge validation and submission into a single API; distinguish blocking vs. advisory validation results in the response.

Blocking: modal forces user to resolve before proceeding.

Advisory: modal asks for confirmation; user can continue, optionally passing a flag to skip validation.

6. Effects

Reduced communication overhead and faster development.

Shortened integration time and fewer code adjustments.

Accelerated testing by clarifying issue ownership.

Easier online issue tracing and fixing.

7. Summary

In short, if the front‑end is handling a lot of business logic, the collaboration standard likely needs improvement; front‑end should focus on interaction and rendering, leaving complex logic to back‑end. Establishing a solid standard takes time, but both sides benefit from patience and mutual understanding.