Interface Contract Security Specification
Trigger Scenarios
- Adding or adjusting HTTP/JSON interfaces
- Frontend-backend joint debugging
- Anomalies in list pages, pagination, filter options, status enums, or detail pages
- The frontend starts to support multiple response shapes
- Some backend interfaces do not use the project's unified success response helper
Core Principles
- Look at the real interface input and output first, then draw conclusions; do not speculate based on frontend types or old memories
- When the backend contract root cause can be fixed, prioritize unifying the backend; frontend compatibility is only a short-term transition
- List, detail, option, or enum interfaces should follow the same success response format
- The pagination structure must be explicitly agreed upon; do not mix arrays and pagination objects long-term
- Temporary compatibility may be retained, but the exit conditions and removal timing must be clearly stated
Checklist
1. Success response wrapping
- Does the list interface use the project's unified success response helper
- Does the detail interface also use the same success response format
- Do the status option, enum, and filter option interfaces still return bare arrays or other special-case structures
- Are error responses consistent with the project's existing patterns
2. List and pagination structure
- Does the frontend currently expect an array, a pagination object, or a unified wrapper
data
- Does the backend actually return something consistent with that expectation
-
page、pageSize、total、items Are the or equivalent fields complete and consistently named
- Is the page number basis consistent, for example starting from 0 or starting from 1
3. Filter options and enum sources
- Does the data returned by the filter options interface come from real logs or real status fields
- Is "filter options empty" truly no data, rather than a contract mismatch
- Are the enum values consistent with the real values in the list data
- When the frontend falls back to generating options, has it been marked as a short-term fallback rather than a long-term official source
4. Field mapping and call chain
- Are the field names used by the frontend derived from real interface returns, rather than local type guesses
- Do the list, detail, and filter interfaces reference the same business field semantics
- If an intermediate transformation layer exists, do the field semantics remain consistent before and after the transformation
5. Temporary compatibility governance
- What specific problem is the current compatibility branch meant to solve
- What is the exit condition for the compatibility branch
- After the backend is unified, is there a plan to remove the dual-format compatibility
- Does the output clearly distinguish between "root cause fix" and "short-term fallback"
6. Verification
- Directly inspect the real interface response or server logs, rather than only looking at frontend behavior
- Verify whether the list, detail, and filter option entry points are all consistent
- Verify the contract behavior under empty, non-empty, and exceptional states
- If a compatibility branch is retained, verify that it does not conceal new contract errors
Common Anti-Patterns
- Seeing that the page can open, accepting long-term frontend compatibility with both array and pagination object formats
- Only fixing the list interface, not the detail interface and status option interface
- Seeing that filter options are empty, backfilling from the current page data first, but not investigating the backend contract
- Guessing field names or return structures from type definitions without evidence
Output requirements
- Clearly distinguish symptoms, the current contract, the expected contract, root-cause fixes, temporary compatibility, and exit conditions
- If the evidence comes from logs, packet captures, or direct interface responses, state the basis explicitly
- If compatibility logic is still retained, explain why it is not being removed immediately this time
