zikai/zPDF_package
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
refactor/cleanup-failfast
zPDF_package/docs/error-handling.md
zikai 25bc00ac51 refactor: 清理死代码 + 提前失败 + 错误记录控制台 
- downloadUrl 提升为顶层纯函数导出, JobList 不再为此实例化整个 api 对象
- createPdfApi 返回对象移除内部用的 getJob / downloadUrl (高内聚)
- useLocale 移除未用的 isZh/pick 返回值
- 移除 4 个死 i18n key (upload.uploading/submitted/failed/networkError)
- App.vue: import {watch} 提升至顶部; onDelete 补 try/catch + console.error
- usePdfApi: pollPending 单任务失败补 console.warn; uploadFile 响应解析失败补 console.error
- docs: 新增 error-handling.md / integration.md (嵌入细节从 README 移入)
- README: 修正 dev 端口 5173->5175; 补 apache2 部署说明
2026-07-28 11:12:37 +08:00

1.2 KiB
Raw Permalink Blame History

错误处理与日志约定

zPDF_package 的错误处理分两层：API 客户端 fail-fast（抛错），UI 层捕获后既写控制台又给用户反馈。

API 客户端（src/composables/usePdfApi.js）

  • load / getJob / remove：fetch 不可用抛 fetch unavailable；非 2xx 抛 HTTP <status>。
  • uploadFile：XHR 不可用抛 XMLHttpRequest unavailable；网络错误 reject network error；响应非 200 时解析 detail 字段，无则 HTTP <status>。
  • pollPending：单个任务查询失败不中断整体轮询，但 console.warn 记录（避免持久故障完全不可见）。
  • downloadUrl：纯函数，无副作用。

UI 层（src/App.vue, src/components/）

  • refresh() 失败：捕获写入 loadError，JobList 显示「加载失败」。
  • onDelete() 失败：console.error 记录 + 写入 loadError 提示用户。
  • Uploader.handle() 失败：捕获写入 errMsg 显示。
  • validateFile 返回 i18n key（非抛错），由 onUpload 翻译后抛 Error(t(key)) 交给 Uploader 显示。

控制台前缀

所有 [zPDF] 前缀的日志来自本子项目，便于嵌入宿主时与宿主日志区分。