Wang1rrr opened a new pull request, #4859:
URL: https://github.com/apache/rocketmq-dashboard/pull/4859
<!-- Make sure the base branch is `rocketmq-studio`: that is the RocketMQ
Studio trunk. -->
### Which Issue(s) This PR Fixes
- Fixes #4858
### Brief Description
`docs/api-spec.md` 搂9 documented two of the six endpoints `DLQController`
exposes. The four missing ones are the ones the console's DLQ drawer actually
calls (`listDLQMessages`, `resendDLQSelected`, `exportDLQMessages`,
`exportDLQExcel` in `web/src/api/message.ts`), so an integrator could not
reproduce the page from the spec.
This adds 搂9.3-搂9.6 plus the shared response-header block, and appends index
rows 99-102:
| section | endpoint | what the spec now records |
| --- | --- | --- |
| 搂9.3 | `GET /api/dlq/{groupName}/messages` | parameters and their bounds,
the `#### DLQMessage` type block, and the note that `total` is the scan hit
count rather than the size of the DLQ topic |
| 搂9.4 | `POST /api/dlq/resend-selected` | the `1`-`100` `msgIds` bound and
the `targetTopic` validation it shares with 搂9.2 |
| 搂9.5 | `GET /api/dlq/export` | that it bypasses the `Result` envelope,
`maxCount` clamping to `min(maxCount, 5000)`, the attachment filename |
| 搂9.6 | `GET /api/dlq/export-excel` | the sheet name and column list, the
`Store Time` zone, and that `msgIds` must be a **repeated** parameter |
| shared | both exports | `X-DLQ-Export-Truncated` / `-FailedQueues` /
`-Limit`, their `Access-Control-Expose-Headers` dependency, and the filename
sanitisation |
| shared | all four | the default `[now - 1h, now]` window, the `5000` scan
cap, and the Apache-only `501` |
Three of these were previously only discoverable from source:
- **The exports do not use the `Result` envelope.** Every other endpoint in
the document returns `{code, message, data}`; these return a raw JSON array and
an `.xlsx` byte stream.
- **Completeness metadata travels in headers**, and is only readable
cross-origin because `CorsConfig.java:49` exposes it.
- **`msgIds[]=a` silently degrades.** `web/src/api/message.ts:309` carries a
code comment explaining that axios's default bracketed form is not bound by
Spring's `@RequestParam List<String>`, so the export quietly covers the whole
time window instead of the selection. `web/src/api/message.ts` had to pin
`paramsSerializer: { indexes: null }` to avoid it. A comment in one client is
the wrong home for a server contract; the spec is.
Formatting follows the conventions already in the file: `#### TypeName` for
a response shape (as 搂4.1's `#### BrokerInfo` and 搂8.1's `#### MessageRecord`
do), parameter tables with 鏄?鍚? and index rows appended at the end of 搂鎺ュ彛閫熸煡
rather than renumbered - rows 90-98 are already out of section order for
exactly that reason, so the diff stays additive (112 insertions, 0 deletions).
Nothing here changes behaviour, so no code or test is touched. Every
statement is read off `DLQController`, `DLQService`, `RocketMQDLQProvider`,
`DLQMessageVO`, `DLQMessageExcelRow`, `DlqExportHeaders` and
`MessagePropertyDisplay` at `4c697f07`.
Out of scope, called out in the issue instead:
`.github/ISSUE_TEMPLATE/doc.yml` still tells contributors to base the branch on
`master`, the same stale-trunk wording #4801 removed from
`PULL_REQUEST_TEMPLATE.md`.
### How Did You Test This Change?
Documentation only. Verified by reading the rendered Markdown and
cross-checking every claim against the sources at `4c697f07`:
```
git diff --stat
docs/api-spec.md | 112
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 112 insertions(+)
```
- additive only: no existing line is rewritten, so 搂9.1 / 搂9.2 and every
later section keep their anchors and numbering
- the file's CRLF line endings are preserved (no whitespace churn in the
diff)
- code fences stay balanced and the two new tables use the same column shape
as their neighbours
- endpoint list reconciled against `rg '@(Get|Post)Mapping'
DLQController.java`: 6 mappings, 6 documented
- index reconciled: `rg '/api/dlq' docs/api-spec.md` now returns 6 paths in
the quick-reference table and 6 in the section bodies
### Checklist
- [x] One coherent change; unrelated modifications are not bundled in
- [x] Commit subject follows Conventional Commits (`feat:` / `fix:` /
`refactor:` / `chore:` / `docs:` / `perf:`)
- [x] Tests added or updated for non-trivial changes, test methods named
`...Test` (documentation only - no behaviour changes)
- [x] New UI text has both Chinese and English entries under `web/src/i18n/`
(no UI text; the new sections follow the document's existing Chinese style)
- [x] Architecture constraints stay green (`mvn test` runs the ArchUnit
checks) - no Java changed
- [x] New source files carry the ASF license header (no new source files)
- [x] Documentation touched where behaviour changed (README / `docs/` /
in-app help) - this *is* the documentation change; `README.md` / `README_zh.md`
do not enumerate DLQ endpoints, so they need no sync
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
