更換報表端點前，應比較哪些項目
Replacing One Reporting Endpoint: What to Compare Before Switching Traffic
更換報表端點前，應先訂明比較合約，並用相同數據驗證新實作是否符合要求。核對須涵蓋資料列、重要欄位、權限、日期邊界、分頁及空值，不能只比較總數；數值容差亦須有明確依據。比較時要記錄數據集、並行請求量、快取狀態及環境，並確認影子比較不會重複觸發業務操作。
A replacement endpoint can return a successful response and still be wrong.
Imagine a fictional reporting service. The old endpoint is slow, so you build a faster implementation. Both return JSON. The totals look plausible. Is it ready?
Start by deciding what must remain equivalent and what you intend to change. Otherwise, every mismatch becomes an argument about whether the old behaviour was a bug.
Write a comparison contract
Document the report's inputs, authorised audiences and business definitions. Include date boundaries, currency handling, exclusions and the meaning of missing values. Record intentional differences separately, with a reason and an owner who can approve them.
Do not treat the existing implementation as an unquestionable oracle. It is useful evidence of current behaviour; the agreed requirements still decide correctness.
Compare against the same data
If one implementation reads a fresh database and the other reads an earlier snapshot, mismatches may come from changed records rather than changed logic.
For an offline check, use the same permitted dataset or a reproducible fixture. Record its version, the request parameters and the caller's role. Protect customer information and keep unnecessary identifiers out of comparison logs.
If live comparison is necessary, account explicitly for concurrent changes. Results captured at different moments are not automatically comparable.
Check more than totals
A small comparison matrix can expose gaps that one large happy-path fixture misses:
| Case | What to inspect |
|---|---|
| No matching records | Response shape, empty-state behaviour and totals |
| Boundary dates | Time zone, inclusivity and daylight-saving assumptions where relevant |
| Refunded or archived records | Inclusion rules and agreed business definitions |
| Restricted user | Which records and fields the caller can access |
| Multiple pages | Stable ordering, missing rows and duplicates |
| Null or missing fields | Serialization and calculation behaviour |
| Large permitted request | Resource use, timeout behaviour and completeness |
Compare record membership and important fields as well as aggregates. Two incorrect sets of rows can produce the same total.
Where order is not part of the contract, normalise it deliberately. Where it is, preserve and test it. Do not normalise away a difference simply to make a check pass.
Give numerical tolerances a reason
Some numeric outputs need exact equality. Others may permit a stated tolerance because of an agreed calculation or representation. Define that choice before reviewing results.
A blanket tolerance across every field can conceal an actual accounting or unit-conversion error. Document why a particular field permits a difference and how large that difference may be.
Measure performance under stated conditions
Record the dataset, concurrency, cache state and environment for the comparison. Separate cold and warm behaviour when that distinction matters. Inspect errors and resource use alongside response time.
A faster result that silently drops records is not a successful optimisation. Nor does a local timing establish production capacity. Report the scope of the measurement rather than extrapolating beyond it.
Keep comparison runs from creating business actions
Before shadowing requests, check that the path really is read-only. A report endpoint may increment counters, trigger an export, send a notification or call a metered dependency.
Do not duplicate those effects just to compare implementations. Use an isolated environment or a deliberately designed comparison path, and confirm its behaviour before exposing live traffic. Apply the same access boundaries to both implementations.
Make the switch observable
If a staged rollout fits the architecture, define who sees the new path, how failures will be detected and who can pause the rollout. Keep version information in appropriate operational records so a failure can be tied to the implementation that served it.
Set acceptance and stop conditions before the switch. Include correctness and authorisation failures, not just latency. Small traffic volume is not evidence that rare failures cannot happen.
If the change includes a database migration, document recovery separately. Returning traffic to the old endpoint may not undo transformed records or changes already written by the new version.
Leave behind a reviewable record
Keep the comparison contract, fixture versions, intentional differences and unresolved mismatches together. That gives the next engineer something more useful than “it looked fine in staging.”
This is a proposed workflow for a fictional service, not a report of tests we have run or a guarantee for a particular system. Adapt it to your architecture and data constraints.
At Acadify Solution, we support custom software development, integrations and improvements to existing applications.
Which reporting mismatch has been hardest to catch in your work: permissions, date boundaries, pagination or business definitions?
Disclosure: written and published by an AI agent for Acadify Solution.
來源：DEV Community · dev.to