企业官网建设流程全解析

• 后端

导读

.value()是 Bluebird 提供的**同步检查（synchronous inspection）机制的核心方法：当某个 Promise 在特定代码路径中已确定被兑现（fulfilled）**时，你可以直接、同步地取出其兑现值，而无需经由始终异步回调的.then()。本文将围绕 docs/docs/api/value.md 展开，完整讲解.value()/.reason()的签名、语义、抛错行为，并结合 src/synchronous_inspection.js 的位域实现、test/mocha/synchronous_inspection.js 的测试用例以及 PromiseInspection 接口，深入剖析其底层原理与实战用法。读完本文，你将掌握在 Bluebird 中安全同步读取 Promise 兑现值/拒绝原因、扁平化异步链，以及借助.reflect()统一处理混合结果的能力。

一、API 签名与核心语义

1.1.value()

根据 value.md 的原始定义：

.value() -> any

• 返回值：该 Promise 的兑现值（fulfillment value）；
• 前提条件：只有在 Promise已经兑现时才能调用；
• 错误行为：如果 Promise 尚未兑现，调用会抛出错误——原文档明确强调："it is a bug to call this method on an unfulfilled promise"（在未兑现的 Promise 上调用此方法属于 bug）。

1.2.reason()

配套的 reason.md 定义了拒绝原因读取方法：

.reason() -> any

• 返回值：该 Promise 的拒绝原因（rejection reason）；
• 前提条件：只有在 Promise已经被拒绝时才能调用；
• 错误行为：如果 Promise 未被拒绝，调用会抛出错误——"it is a bug to call this method on an unrejected promise"。

1.3 为什么必须先做状态检查

由于这两个方法在状态不匹配时会直接抛错，原文档给出了明确的守卫建议：

在不保证该 Promise 一定已兑现的代码路径中，你应该先检查 .isFulfilled()；在不保证一定已拒绝的路径中，先检查 .isRejected()。

也就是说，正确的调用范式是「先判定、再取值」：

if (promise.isFulfilled()) { const value = promise.value(); // 安全 } if (promise.isRejected()) { const reason = promise.reason(); // 安全 }

二、抛错行为与错误消息的源码级验证

.value()/.reason()的抛错并非空谈，其错误类型与消息在源码中有明确实现。在 src/constants.js 中定义了对应的错误消息常量：

CONSTANT(INSPECTION_VALUE_ERROR, "cannot get fulfillment value of a non-fulfilled promise\n\n\ See http://goo.gl/MqrFmX\n"); CONSTANT(INSPECTION_REASON_ERROR, "cannot get rejection reason of a non-rejected promise\n\n\ See http://goo.gl/MqrFmX\n");

而在 src/synchronous_inspection.js 中，这两个方法被实现为对状态位（bitField）的检查 + 抛 TypeError：

var value = PromiseInspection.prototype.value = function () { if (!this.isFulfilled()) { throw new TypeError(INSPECTION_VALUE_ERROR); } return this._settledValue(); }; var reason = PromiseInspection.prototype.error = PromiseInspection.prototype.reason = function () { if (!this.isRejected()) { throw new TypeError(INSPECTION_REASON_ERROR); } return this._settledValue(); };

这里有两个值得注意的实现细节：

1. 错误类型为TypeError，并携带上面定义好的消息文本，便于定位问题；
2. reason是error的别名——同一个函数同时挂载到PromiseInspection.prototype.error与PromiseInspection.prototype.reason上，意味着在 Bluebird 内部.error()与.reason()语义等价。

2.1 测试用例的佐证

test/mocha/synchronous_inspection.js 用专门的describe(".value()")/describe(".reason()")分组验证了「状态不匹配必须抛错」的行为：

describe(".value()", function() { specify("of unfulfilled inspection should throw", function() { Promise.reject(1).reflect().then(function(inspection) { try { inspection.value(); // 已拒绝的 inspection 调 .value() -> 抛错 } catch (e) { return Promise.resolve(); } assert.fail(); }); }); specify("of unfulfilled promise should throw", function() { var r = Promise.reject(1); r.reason(); try { r.value(); // 已拒绝的 promise 调 .value() -> 抛错 } catch (e) { return Promise.resolve(); } assert.fail(); }); });

对应的.reason()分组则验证了「已兑现对象调.reason()必须抛错」。这些用例直接印证了原文档关于「调用未匹配状态的方法是 bug」的表述——在编写自己的代码时，务必先用isFulfilled()/isRejected()做守卫。

三、核心实战场景：同步检查消除回调嵌套

3.1 场景背景

原文档 value.md 本身篇幅精炼，但其指向的核心能力——同步检查——的完整使用场景，记录在配套文档 synchronous-inspection.md 中。该文档开宗明义地指出：

在特定代码路径中，我们常常能确定某个 Promise 此刻必然已兑现——此时再用.then()取它的值会非常不便，因为回调总是被异步调用。

注意：根据 synchronous-inspection.md 的说明，在 Bluebird 较新的版本中，设计决策是把.value()、.reason()及其他检查方法直接暴露在 Promise 实例上，以便简化上述场景——每个 Promise 都实现了 PromiseInspection 接口。

3.2 嵌套地狱 vs 扁平取值

以经典的「认证（authenticate）」流程为例。传统写法需要把前面步骤的值一路闭包嵌套下去（示例源自 Q 文档，Bluebird 文档收录）：

function authenticate() { return getUsername().then(function (username) { return getUser(username); // chained because we will not need the user name in the next event }).then(function (user) { // nested because we need both user and password next return getPassword().then(function (password) { if (user.passwordHash !== hash(password)) { throw new Error("Can't authenticate"); } }); }); }

而利用「走到密码校验这一步时，userpromise 必然已经兑现」这一确定性，可以借助.value()把嵌套压平：

function authenticate() { var user = getUsername().then(function(username) { return getUser(username); }); return user.then(function(user) { return getPassword(); }).then(function(password) { // Guaranteed that user promise is fulfilled, so .value() can be called here if (user.value().passwordHash !== hash(password)) { throw new Error("Can't authenticate"); } }); }

两者的对比非常直观：后者无论前面需要引用多少个历史变量，缩进始终保持平坦；而前者每多一个前置值，就得多一层嵌套。这就是同步检查的价值所在——在「代码路径保证」成立的前提下，用一次同步读取换掉一层异步回调。

四、PromiseInspection 接口：value()/reason()的所属契约

4.1 接口定义

promiseinspection.md 给出了完整的接口形态：

interface PromiseInspection { any reason() any value() boolean isPending() boolean isRejected() boolean isFulfilled() boolean isCancelled() }

该接口由Promise实例以及.reflect() 返回的PromiseInspection对象共同实现。也就是说，value()和reason()在这两类对象上行为一致。

4.2 配套的状态判定方法

要在使用value()/reason()之前完成状态守卫，需要以下配套方法（它们全部定义在 src/synchronous_inspection.js 中，并统一通过this._target()解析到目标 Promise 后再做位域判断）：

五、底层实现：位域（bitField）驱动的高性能检查

5.1 状态存储：单个整数承载全部状态

Bluebird 以性能著称，同步检查方法的高效正源于其位域（bitField）设计。在 src/constants.js 中可以看到._bitField的完整布局注释：

//Layout for ._bitField //[RR]XO GWFN CTBH IUDE LLLL LLLL LLLL LLLL //... //F = isFulfilled //N = isRejected //E = isCancelled //L = Length, 16 bit unsigned

对应的位掩码常量：

CONSTANT(IS_FULFILLED, 0x2000000|0); CONSTANT(IS_REJECTED, 0x1000000|0); CONSTANT(IS_CANCELLED, 0x10000|0); CONSTANT(IS_REJECTED_OR_FULFILLED, IS_REJECTED | IS_FULFILLED); CONSTANT(IS_REJECTED_OR_FULFILLED_OR_CANCELLED, IS_REJECTED | IS_FULFILLED | IS_CANCELLED); CONSTANT(IS_FATE_SEALED, IS_REJECTED | IS_FULFILLED | IS_FOLLOWING | IS_CANCELLED);

5.2 判定即「与运算」

src/synchronous_inspection.js 中的状态判定全部是一次位与运算，这就是同步检查零开销的来源：

var isFulfilled = PromiseInspection.prototype.isFulfilled = function() { return (this._bitField & IS_FULFILLED) !== 0; }; var isRejected = PromiseInspection.prototype.isRejected = function () { return (this._bitField & IS_REJECTED) !== 0; }; var isPending = PromiseInspection.prototype.isPending = function () { return (this._bitField & IS_REJECTED_OR_FULFILLED_OR_CANCELLED) === 0; }; var isResolved = PromiseInspection.prototype.isResolved = function () { return (this._bitField & IS_REJECTED_OR_FULFILLED) !== 0; };

而实际挂在Promise.prototype上的公开方法（src/synchronous_inspection.js）会先通过_target()解析跟随链：

Promise.prototype.value = function() { return value.call(this._target()); }; Promise.prototype.reason = function() { var target = this._target(); target._unsetRejectionIsUnhandled(); return reason.call(target); };

这里有一个容易忽略但非常重要的细节：调用Promise.prototype.reason()时会先执行_unsetRejectionIsUnhandled()，即「读取拒绝原因」这一动作会清除该拒绝的未处理标记。这意味着当你在拒绝之后同步调用.reason()读取原因时，Bluebird 不会再将该拒绝视为未处理的 rejection 而触发告警——这也是对拒绝进行「消费」的合法方式之一。

PromiseInspection的构造（src/synchronous_inspection.js）同样值得注意：

function PromiseInspection(promise) { if (promise !== undefined) { promise = promise._target(); this._bitField = promise._bitField; this._settledValueField = promise._isFateSealed() ? promise._settledValue() : undefined; } ... }

它在构造时对_target()快照_bitField，并且仅当 fate 已封存（_isFateSealed()，即已拒绝/已兑现/正在跟随/已取消，参见 constants.js）时才读取结算值——这保证了 inspection 对象捕获的是创建时刻的稳定状态。

六、与.reflect()配合：统一处理「兑现或拒绝」的混合结果

value()/reason()最实用的组合玩法是配合 .reflect()。.reflect()返回一个永远成功的 Promise，其兑现值是一个实现 PromiseInspection 接口的对象，忠实反映原 Promise 的结算结果：

.reflect() -> Promise<PromiseInspection>

6.1 实现settleAll：等待一组 Promise 全部结算

var promises = [getPromise(), getPromise(), getPromise()]; Promise.all(promises.map(function(promise) { return promise.reflect(); })).each(function(inspection) { if (inspection.isFulfilled()) { console.log("A promise in the array was fulfilled with", inspection.value()); } else { console.error("A promise in the array was rejected with", inspection.reason()); } });

6.2 实现settleProps：对象的每个属性独立结算

var object = { first: getPromise1(), second: getPromise2() }; Promise.props(Object.keys(object).reduce(function(newObject, key) { newObject[key] = object[key].reflect(); return newObject; }, {})).then(function(object) { if (object.first.isFulfilled()) { console.log("first was fulfilled with", object.first.value()); } else { console.error("first was rejected with", object.first.reason()); } })

在这两个例子中，inspection.value()/inspection.reason()的使用都严格遵循「先isFulfilled()/isRejected()判定、再取值」的契约——这正是 value.md 强调的防错姿势。

6.3.reflect()的底层：PromiseInspection实例的构造

从 src/settle.js 可以看到，Bluebird 在内部正是为每个结算结果构造一个PromiseInspection实例：

SettledPromiseArray.prototype._promiseFulfilled = function (value, index) { var ret = new PromiseInspection(); ret._bitField = IS_FULFILLED; ret._settledValueField = value; return this._promiseResolved(index, ret); }; // 对应的 _promiseRejected 则以 IS_REJECTED 构造

也就是说，你在reflect()结果上调用的.value()/.reason()/.isFulfilled()，最终都会落到第一节分析的同一套PromiseInspection.prototype实现上。Promise 实例与 PromiseInspection 实例共享同一套同步检查逻辑，这是文档所述「Promise 也实现 PromiseInspection 接口」的直接代码证据。

七、总结：.value()/.reason()使用守则

结合 value.md、reason.md 与源码、测试的交叉验证，可以归纳出以下使用守则：

1. 只在有把握的路径上使用：.value()要求 Promise 已兑现，.reason()要求已拒绝，否则抛出TypeError（消息见 constants.js）；
2. 先用判定方法做守卫：不确定状态时，先调用.isFulfilled()/.isRejected()/.isPending()/.isCancelled()，再取对应值；
3. 用于压平嵌套：当「到达某段代码意味着前置 Promise 必然已兑现」时，用.value()替代一层.then()回调，让链式代码保持平坦（见 synchronous-inspection.md 的 authenticate 示例）；
4. 配合.reflect()统一结算：需要批量等待「有成功有失败」的 Promise 集合时，reflect()+value()/reason()是最佳组合（见 reflect.md）；
5. 注意.reason()的副作用：读取.reason()会清除该拒绝的未处理标记，可用于合法地「消费」拒绝（见 src/synchronous_inspection.js）；
6. 性能优势：所有状态判定均为位与运算（见 constants.js 与 synchronous_inspection.js），同步检查几乎零成本。

更多相关 API 可查阅 API 参考总览，以及配套文档 .isFulfilled()、.isRejected()、.isPending()、.isCancelled()、PromiseInspection 与 .reflect()。

• 后端