企业官网建设流程全解析

• 前端
• CMS

是 WordPress.com 桌面端/Web 应用（WP Calypso）中用于通过 WP.com 服务端发起 WHOIS 查询的轻量级 React 组件。本文将以 client/components/data/query-whois/README.md 为骨架，结合组件实现、Redux action/reducer、selector 与真实业务调用场景，完整还原"渲染即查询、数据进 Redux、页面按需消费"的数据预取模式，帮助你理解并复用在 Calypso 中"查询型数据组件"的标准写法。

组件定位：无渲染、无子节点的数据预取器

在 WP Calypso 中，QueryWhois属于一组约定俗成的Query 组件（data-fetching component）。这类组件遵循统一的设计哲学：

• 只负责触发数据请求，不负责渲染任何 UI；
• 不接受 children，也不会渲染任何自身内容；
• 渲染组件本身即是一次"副作用"，数据落地到全局 Redux 状态树后，由页面上其它展示型组件通过 selector 消费。

原文档对这一点给出了非常明确的定义（README.md）：

<QueryWhois />is a React component used to perform a WHOIS lookup via WP.com server-side. The queried domain must be owned by the user.

其中有两个关键约束值得注意：

1. 查询经由 WP.com 服务端完成，即客户端不直接连接注册局 WHOIS 服务，而是调用 WP.com 的 REST 接口，由服务端代理查询；
2. 被查询的域名必须归属于当前登录用户，组件本身不校验所有权，但服务端接口会在权限不足时拒绝请求。

快速上手：最小可用用法

原文档给出的用法极其简洁——渲染组件并传入domain即可：

function MyComponent() { const domain = 'example.com'; return <QueryWhois domain={ domain } />; }

需要注意的细节：

• 组件返回null，因此无论放在 JSX 树的哪个位置都不会产生额外 DOM 节点；
• 组件只接受一个 prop：domain；
• 由于查询的是"当前用户拥有的域名"，这里的domain通常是完整注册域名（如example.com），而非子域名或带协议头的 URL。

在真实页面中，它往往与其他 Query 组件并列渲染，例如批量编辑联系信息页面同时拉取站点域名列表与 WHOIS 数据（见下文"实际业务场景"）。

Props 契约：唯一必需的domain

组件的 propTypes 定义在 index.jsx：

QueryWhois.propTypes = { domain: PropTypes.string.isRequired, };

由于domain是必需 prop，若未传入，React 会在开发模式下给出 PropTypes 警告，同时组件内部的请求函数也会因domain为空而跳过 dispatch（见下文实现解析）。

组件源码逐行解析：防重复请求与 effect 触发

组件的完整实现在 client/components/data/query-whois/index.jsx，全文仅 27 行，核心逻辑如下：

import PropTypes from 'prop-types'; import { useEffect } from 'react'; import { useDispatch } from 'react-redux'; import { requestWhois } from 'calypso/state/domains/management/actions'; import isRequestingWhois from 'calypso/state/selectors/is-requesting-whois'; const request = ( domain ) => ( dispatch, getState ) => { if ( domain && ! isRequestingWhois( getState(), domain ) ) { dispatch( requestWhois( domain ) ); } }; function QueryWhois( { domain } ) { const dispatch = useDispatch(); useEffect( () => { dispatch( request( domain ) ); }, [ dispatch, domain ] ); return null; }

这段实现蕴含了几个重要设计：

1. 依赖注入式 thunk：request(domain)返回一个接收(dispatch, getState)的 Redux thunk，把"是否发起请求"的决策权交给 thunk 内部，而不是在组件里直接判断。
2. 双重防重：
   • 空值防护：domain为空时不发起请求；
   • 进行中防护：调用 selectorisRequestingWhois(getState(), domain)检查该域名是否已有请求正在进行，避免重复请求同一域名。
3. useEffect依赖数组：[ dispatch, domain ]意味着domain变化时组件会重新触发查询；dispatch引用稳定，不会引起多余重跑。domain变为不同域名时，会按新域名再次发起请求。
4. 渲染副作用分离：组件恒返回null，所有副作用都被收敛在 effect 中，便于测试与复用。

从源码结构看，这也是整个 Calypso 中大量QueryXxx组件（如QuerySiteDomains）共同采用的标准模式：组件壳 + 防重 thunk + Redux action。

Redux 数据流：从组件渲染到状态落地

QueryWhois只是链路的起点，真正的网络请求发生在 action 层。dispatch 的requestWhois定义于 client/state/domains/management/actions.tsx：

export function requestWhois( domain: string ) { return ( dispatch: CalypsoDispatch ) => { dispatch( { type: DOMAIN_MANAGEMENT_WHOIS_REQUEST, domain, } ); return wpcom.req .get( `/domains/${ domain }/whois` ) .then( ( whoisData: WhoisData ) => { dispatch( receiveWhois( domain, whoisData ) ); dispatch( { type: DOMAIN_MANAGEMENT_WHOIS_REQUEST_SUCCESS, domain, } ); } ) .catch( ( error: Error ) => { dispatch( { type: DOMAIN_MANAGEMENT_WHOIS_REQUEST_FAILURE, domain, error, } ); } ); }; }

完整流程如下：

渲染 <QueryWhois domain="example.com" /> └─ useEffect → dispatch(request(domain)) ├─ isRequestingWhois(state, domain) 为 false 时放行 ├─ dispatch: DOMAIN_MANAGEMENT_WHOIS_REQUEST （标记请求中） ├─ wpcom.req.get(`/domains/${domain}/whois`) （服务端 WHOIS 查询） ├─ 成功 → DOMAIN_MANAGEMENT_WHOIS_RECEIVE（写入数据） │ → DOMAIN_MANAGEMENT_WHOIS_REQUEST_SUCCESS（清除请求中标记） └─ 失败 → DOMAIN_MANAGEMENT_WHOIS_REQUEST_FAILURE（清除请求中标记并记录 error）

对应的 action type 常量集中在 client/state/action-types.ts：

DOMAIN_MANAGEMENT_WHOIS_RECEIVE DOMAIN_MANAGEMENT_WHOIS_REQUEST DOMAIN_MANAGEMENT_WHOIS_REQUEST_FAILURE DOMAIN_MANAGEMENT_WHOIS_REQUEST_SUCCESS DOMAIN_MANAGEMENT_WHOIS_SAVE DOMAIN_MANAGEMENT_WHOIS_SAVE_FAILURE DOMAIN_MANAGEMENT_WHOIS_SAVE_SUCCESS DOMAIN_MANAGEMENT_WHOIS_UPDATE

这里可以观察到完整的"查询/保存/更新"生命周期：除只读查询外，saveWhois会通过POST /domains/${domain}/whois把修改后的联系信息写回注册局，并可携带transfer_lock参数决定是否在更新后设置 60 天转移锁（见 actions.tsx）。QueryWhois负责的是其中"查询"这一半。

状态管理：reducer、schema 与 selector

Reducer 结构

WHOIS 相关的 Redux 状态由 client/state/domains/management/reducer.js 维护，经combineReducers合并为三个子状态（见 reducer.js#L116-L120）：

export default combineReducers( { items, isRequestingWhois, isSaving, } );

• isRequestingWhois：由keyedReducer('domain', ...)按域名分键，DOMAIN_MANAGEMENT_WHOIS_REQUEST置为true，成功/失败后复位为false（reducer.js#L15-L25）。这正是QueryWhois防重逻辑读取的状态。
• items：以域名为 key 缓存 WHOIS 数据对象，经withSchemaValidation(domainWhoisSchema, ...)包裹做运行时校验；收到DOMAIN_MANAGEMENT_WHOIS_RECEIVE时整体写入，收到DOMAIN_MANAGEMENT_WHOIS_UPDATE时把新的注册人联系信息合并进对应记录（reducer.js#L91-L114）。
• isSaving：记录保存请求的pending/success/error状态（reducer.js#L34-L63）。

校验 Schema

数据写入前会经过 client/state/domains/management/schema.js 定义的 JSON Schema 校验，它刻画了 WHOIS 记录中联系信息字段的基本形态：

export const domainWhoisSchema = { type: 'object', additionalProperties: true, patternProperties: { first_name: { type: 'string' }, last_name: { type: 'string' }, email: { type: 'string' }, phone: { type: 'string' }, address1: { type: 'string' }, address2: { type: 'string' }, city: { type: 'string' }, state: { type: 'string' }, postal_code: { type: 'string' }, country_code: { type: 'string' }, }, };

Selector：读取请求状态与数据

• 请求状态：client/state/selectors/is-requesting-whois.js 返回布尔值，供组件做加载判断：

export default function isRequestingWhois( state, domain ) { return state?.domains?.management?.isRequestingWhois?.[ domain ] ?? false; }

• 数据读取：client/state/selectors/get-registrant-whois.js 从items中取出该域名的 WHOIS 记录数组，再借助 client/lib/domains/whois/utils.js 中的findRegistrantWhois筛选出type === 'registrant'的注册人记录：

export default function getRegistrantWhois( state, domain ) { const whoisContacts = state?.domains?.management?.items?.[ domain ] ?? []; return findRegistrantWhois( whoisContacts ); }

WHOIS 记录的两种类型定义在 client/lib/domains/whois/constants.js：REGISTRANT（注册人）与PRIVACY_SERVICE（隐私保护服务）。

响应数据结构：WhoisData 契约

服务端返回的完整 WHOIS 数据契约定义在 client/state/domains/management/types.ts，主要字段如下：

注意：WhoisDataEntry中的字段（如fname、sa1）与 schema 中使用的字段名（如first_name、address1）并不完全一致——前者是服务端返回的缩写命名，后者是保存/展示时使用的完整命名。这是从源码结构中观察到的差异，实际对接时需留意字段映射。

实际业务场景：两个真实消费方

QueryWhois在 Calypso 中主要有两个典型调用场景，它们共同验证了"渲染即预取"模式的价值。

场景一：ICANN 邮箱验证卡片

在 client/my-sites/domains/domain-management/components/icann-verification/index.jsx 中，当contactDetails（注册人联系信息）尚未从状态中取到时，页面直接渲染QueryWhois触发拉取：

if ( ! contactDetails ) { return <QueryWhois domain={ selectedDomainName } />; }

该组件通过getRegistrantWhoisselector 消费数据，拿到注册人邮箱后展示"验证您的邮箱地址"卡片，并提供重新发送 ICANN 验证邮件的入口（resendIcannVerification）。

场景二：批量编辑联系信息页

client/my-sites/domains/domain-management/edit-contact-info-page/bulk-edit-contact-info-page.tsx 是更复杂的用法：用户从域名表格中勾选多个域名后进入批量编辑页，组件对每一个选中的域名渲染一个QueryWhois，并以域名作为key：

{ selectedDomains?.map( ( domain ) => ( <QueryWhois domain={ domain.domain } key={ domain.domain } /> ) ) }

同时，页面通过isRequestingWhoisSelector轮询任一域名是否仍在请求中，作为整页加载态（isDataLoading）的一部分（bulk-edit-contact-info-page.tsx#L121-L132）：

const isRequestingWhois = useSelector( ( state: IAppState ) => selectedDomains?.some( ( domain ) => isRequestingWhoisSelector( state, domain.domain ) ) );

这一场景展示了 Query 组件的两个扩展要点：

1. 一对多预取：通过map渲染多个实例，每个域名独立触发请求，key保证 React 复用/卸载逻辑正确；
2. 请求态驱动 UI：把多个域名的isRequestingWhois聚合起来，控制骨架屏或占位符的显示，避免用户看到"未就绪"的表单。

最佳实践小结

从QueryWhois的完整实现与消费方式中，可以提炼出在 Calypso 中编写查询型数据组件的几条通用经验：

1. 组件恒返回null，把网络请求封装为 useEffect 副作用，便于任意位置挂载；
2. 在 thunk 内做防重判断（isRequestingWhoisselector + 空值检查），避免多个页面实例对同一域名发起重复请求；
3. 请求生命周期三段式（REQUEST → RECEIVE/SUCCESS/FAILURE）写入 Redux，让"加载中/成功/失败"状态可被任意页面消费；
4. 数据按域名分键缓存（keyedReducer('domain')），天然支持多域名场景与跨页面复用；
5. 消费端使用 selector 而非直接访问 action，保持状态读取路径统一（如getRegistrantWhois、isRequestingWhois）；
6. 需要批量预取时，用map渲染多个实例并指定稳定的key，同时聚合请求态驱动页面加载 UI。

若要深入阅读，推荐按以下路径继续探索：组件实现 index.jsx → action 定义 actions.tsx → reducer 与 schema reducer.js、schema.js → selectors is-requesting-whois.js、get-registrant-whois.js → 业务消费方 icann-verification/index.jsx 与 bulk-edit-contact-info-page.tsx。

• 前端
• CMS