团队规范 Promise 封装的核心是统一行为、可预测、易维护：强制返回标准 Promise，严格遵循 pending→fulfilled/rejected 单向流转；成功 resolve 纯数据，失败 reject 标准 Error；内置超时与分层错误分类；链式调用契约明确，禁止隐式状态穿透；提供 fetchWithAuth、retryable 等可组合原子能力。

团队中规范 Promise 接口封装，核心是统一行为、可预测、易维护。不是写得“能用”，而是让每个成员调用时不用查文档就知道它怎么响应、怎么报错、怎么超时、怎么重试。

统一构造与状态语义

所有封装函数必须返回标准 Promise 实例，且严格遵循 pending → fulfilled / rejected 的单向流转。禁止手动修改已 settled 的 Promise 状态，也不允许在 resolve/reject 后继续执行副作用逻辑。

• 接口成功时，只调用 resolve(data)，data 应为纯对象或基础类型，避免传入未序列化的实例（如 Date、RegExp）
• 接口失败时，统一 reject(new Error(message))，而非字符串或自定义对象；Error 实例自带 stack，便于排查
• HTTP 错误码（如 401、500）必须转为 rejected，不能仅靠 status === 200 判断成功——后端可能返回 200 + { code: 500, msg: "xxx" }

强制超时与错误分类

网络请求类 Promise 必须内置超时机制，且错误需分层捕获：网络层、协议层、业务层。

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• 用 Promise.race([fetch(), withTimeout(8000)]) 封装 fetch，避免无响应挂死
• 错误对象应带 type 字段，例如：{ type: 'NETWORK_TIMEOUT', message: '请求超时' } 或 { type: 'BUSINESS_ERROR', code: 4001, data: {...} }
• 不把 401 自动跳登录页——那是业务逻辑，Promise 封装只负责“告知失败”，由上层决定如何响应

链式行为可预期

每个 then/catch 返回的新 Promise 必须明确其输入输出契约，避免隐式状态穿透。

立即学习“Java免费学习笔记（深入）”；

• then 回调里若返回普通值（如字符串、对象），下游得到 fulfilled 状态；若 throw 或返回 rejected Promise，下游自动进入 catch 流程
• 禁止在 then 里做副作用操作却不返回值（如只 console.log 不 return），这会让后续 .then 拿到 undefined，容易引发空值错误
• 统一使用 .catch() 统一收口错误，不依赖每个 then 自己写失败回调；但注意 catch 只捕获上游未处理的 rejected，不是万能兜底

暴露可组合的原子能力

封装不是把所有逻辑塞进一个函数，而是提供可拼装的“乐高块”：

• fetchWithAuth(url, opts)：自动注入 token、处理 401
• retryable(promise, max = 3)：对任意 Promise 增加重试能力
• throttle(promise, delay = 300)：防抖封装，适合搜索建议等场景
• 所有工具函数也返回 Promise，保持类型一致，支持直接接入链式调用