外网版本： http://sd.jd.com/article/59660?shareId=30445&isHideShareButton=1

一、业务背景：为何要进行一码三端改造？

2025年7月，工信部提出明确要求，规定在2025年12月31日前，鸿蒙系统需与iOS、安卓系统全面对齐。根据该要求，京东APP内所有产品模块须保持各平台功能一致，并支持多模式适配，包括大字版、深色模式、大屏、多语言、折叠屏等多种形态。作为日均承载上亿PV访问量的核心交易链路，订单模块亦面临前所未有的业务改造挑战。经过半年的深入实践，订单业务成功实现鸿蒙平台于12月底与安卓、iOS对齐的目标，更进一步将Taro一码多端的代码回跨至安卓与iOS平台。本文将从业务模块视角出发，系统性地分享我们在改造过程中的经验、方法及可复用的实践方案，为其他业务模块的动态化转型提供参考与借鉴。

1.1 多端开发的现实困境：三倍工作量

多端开发方式越来越难跟上业务快速变化的需求，排期频繁调整，升级压力持续增大，技术债务的积累也对业务创新形成了制约。在此背景下，还需承担鸿蒙端的开发任务。在传统开发模式下，安卓、iOS与鸿蒙三端需分别投入研发资源进行独立开发与维护，导致开发工作量呈三倍增长。

1.2 一致性挑战：用户体验风险

三端实现的技术差异导致用户体验存在不一致性，用户在安卓、iOS与鸿蒙设备之间切换时，常感到困惑与不适，这种不统一直接影响了用户转化率与满意度。

三端开发的差异还体现在架构设计、性能优化及体积控制等多个方面：同一问题需针对不同技术栈分别制定解决方案，目标与实际效果往往难以统一，统一标准与系统化改造闭环的建立亦面临挑战。因此，推进动态化方案以重构订单全链路业务已成为必然趋势。

二、改造前准备：业务侧关键基础工作

订单模块改造涉及15个页面、22个弹层，共400余项功能开发点。改造成功的关键在于业务场景梳理，需多维度拆解、全面覆盖并形成详尽文档。采用资深开发人员经验结合AI工具，共完成209篇业务梳理文档。此外，通过清理冗余代码和技术债务，提升系统效率与可维护性。

2.1 业务场景梳理：成功改造的基石

订单模块十几年的业务代码逻辑复杂且繁重。业务场景的梳理是整个改造项目成功实施的基础，直接关系到改造工作的完整性以及系统上线切换的可行性。若关键业务场景遗漏，将可能导致上线后功能缺失、用户体验下降，甚至引发业务损失等严重后果。因此，业务场景梳理作为改造项目的首要任务，需重点关注以下几个方面：

2.1.1 多维度场景拆解：全面业务覆盖

本项目采用系统化的多维度场景拆解方法，全面覆盖各类业务触点。首先，按页面进行划分，明确各页面上线的里程碑节奏；其次，针对每个页面梳理其范围内的功能点及弹层内容；最后，合理拆分任务子项。依据拆分结果，统筹安排梳理与开发任务，确保工作有序推进。对每个任务子项，需从功能细节、数据流转、异常处理机制、数据样例、埋点逻辑及UI交互等方面进行全面梳理，形成详尽文档，确保所有功能点无遗漏。

2.1.2 专家经验+AI工具：深度逻辑梳理

如何实现全面的对比与功能梳理？除了依靠资深开发人员的经验，还需借助AI工具，以提升功能梳理的准确性与完整性。同时，针对业务逻辑较为复杂的三级页面，利用AI进行精准、高效的文档梳理，显著提升了整体梳理效率。通过原生开发人员的业务经验与AI技术能力的有机结合，最终共完成了209篇高质量的业务梳理文档。

2.1.3 清理技术债务：冗余代码治理

本次对历史楼层进行了全面而深入的梳理与优化。由于历史原因，部分楼层多次尝试推动下线，但始终未能实现完整下线，导致系统中仍残留部分历史切量，影响整体架构的清晰度与可维护性。同时，业务上线后从未被打开的开关也长期存在于系统中，不仅增加了维护成本，也带来了潜在的隐患。针对这些问题，我们与产品团队进行了充分沟通与确认，统一评估了下线可能带来的影响，确保在不影响现有业务的前提下，逐步清理这些历史遗留问题。通过本次梳理，我们不仅清除了系统中的“历史债务”，还对部分冗余的业务内容进行了减重处理，提升了系统的整体效率与可扩展性，为后续的优化与迭代打下了坚实的基础。

2.2 任务分解与管理

对订单系统功能进行详细分解，覆盖所有业务场景，分析逻辑关系，确保任务可执行。按节点分批提测，明确依赖，提升效率，确保项目按时高质量完成。

2.2.1 精细化任务分解

我们将订单16个页面、功能细节分解为390多个具体任务，确保每一个业务场景和功能点都得到充分覆盖，无任何遗漏。在任务拆解过程中，我们不仅关注功能实现的完整性，还深入分析了各任务之间的业务逻辑关系，确保任务划分的合理性和可执行性。按照上线的里程碑节点，我们将任务分批次进行提测，每个批次的任务都明确了其在整体业务流程中的位置，以及与其他任务之间的前后依赖关系。通过合理安排提测顺序，实现任务之间的解耦，最大程度减少对测试工作的干扰，保障测试流程的高效推进。

2.2.2 任务进展跟进

同时，我们制定了详细的分批提测任务清单和对应的时间节点，确保每个阶段的业务推进有据可依，业务连续性得到充分保障。在执行过程中，我们建立了完善的任务状态跟踪机制，通过每日实时监控和更新任务进展，确保项目团队对整体进度和关键节点有清晰的掌握。所有业务风险也会在第一时间同步给相关负责人，确保问题能够被及时识别和处理。对于待解决的问题，我们按照其重要性和紧急程度进行分类排序，优先处理对业务影响较大的问题，确保关键路径上的任务能够顺利推进，整体项目按时、高质量交付。

2.3 外部依赖管理：全面识别外部依赖

“一码三端”改造中，实现一套代码在三端内外环境的无缝融合与顺畅通信是关键。需识别三类外部依赖：Taro框架功能组件、H5及小程序等跳转链接、业务模块间的跨端协议。针对每类依赖，制定处理策略与管理机制，确保三端功能与体验一致。

2.3.1 Taro SDK与基础组件依赖识别

本项目涉及上拉下拉加载组件、网络库、基础弹窗、webView、埋点、缓存、原生通信机制等60余项依赖项，业务侧在前期必须明确识别并根据依赖程度合理划分优先级。由于多数组件需多个模块协同开发，在项目周期紧张的情况下，尽早识别相关依赖，避免对后续开发与测试节奏造成影响。

2.3.2 h5、小程序外部跳转链接识别

对于端侧代码而言，通常不会在客户端中硬编码链接。然而，在一码多端的模式下，必须对所有来源的链接进行系统梳理，确保各终端对应的业务落地页已完成适配工作。例如，当部分页面尚未在鸿蒙端完成适配验证时，应首先确认下游适配情况，暂不支持的情况做好屏蔽处理，以避免因盲目跳转而引发线上事故。

2.3.3 业务模块间多端协议识别

订单模块是用户购前与购后链路中的核心中间模块，前置与商品详情、购物车、收银台及结算等环节紧密关联，后置则与售后、客服、履约及复购等多业务模块存在交互。在原生代码中，许多交互均为直接调用实现。在一码三端的开发阶段，必须进行模块解耦，因为一码三端架构无法依赖任何模块的源码，所有通信，包括订单模块内部16个页面之间的交互，均需通过协议对接完成，因此该部分的改造工作量较大。

订单模块内部共统一了16条协议以实现对齐，同时调用其他业务模块共涉及69条原生协议。通过团队的持续努力，已有70%的协议实现了三端一致性。对于部分难以统一的场景，订单模块在Taro业务代码中根据具体场景进行差异化处理，既保障了用户体验，也兼顾了项目交付节奏。

2.3.4 服务端逻辑处理识别

在历史方案中，部分逻辑服务端会对安卓和iOS平台进行差异化处理，例如字段名称、字段类型及结构等方面的处理。这种差异化的处理方式主要是由于不同平台在数据格式、接口规范以及系统行为上存在一定的差异，因此服务端需要针对不同平台进行适配和兼容性处理。在实现一码三端之前，需确保服务端API能够准确识别并处理来自Taro端的请求，提前进行统一规划，以避免逻辑混淆及数据不一致的问题。这包括对请求头、参数格式、返回结构等进行标准化设计，确保无论请求来自安卓、iOS还是Taro端，服务端都能正确解析并返回一致的数据结构。此外，还需要在开发初期就与服务端团队进行充分沟通，明确接口规范和数据格式，确保前后端协作顺畅，提升整体开发效率和系统稳定性。

三、核心业务难点与解决方案

3.1 业务多模式适配挑战

在订单模块的一码三端改造过程中，构建了一个基于实际工程代码的多模式适配体系，以满足不同终端和用户群体的多样化需求。京东App多模式适配场景非常丰富，涵盖多语言适配、暗黑模式、大字版、老年版、大屏横屏模式、换肤主题、无障碍访问等多个方面。每一个适配场景都需要业务开发团队投入大量精力进行适配和优化，确保在不同设备和用户偏好下，依然能够提供稳定、流畅、友好的用户体验。

统一设备状态管理架构

通过采用 Zustand 状态管理库，并结合 [`useDevice.ts`](apps/app_order/src/hooks/useDevice.ts) 钩子，我们实现了对设备信息的全面采集。该方案基于实际工程代码，构建了多模式适配机制，从而使得订单模块能够有效支持多样化的用户需求。

import { create } from 'zustand'

export enum Theme {
  LIGHT = 'light',
  DARK = 'dark',
}

export enum Lang {
  ENUS = 'en-US',
  ZHCN = 'zh-CN',
  ZHTW = 'zh-TW',
}

export enum Age {
  YOUNG = '2',
  NORMAL = '0',
  OLD = '1',
}

暗黑场景适配

//useDevice.ts
const themeChange = useCallback(
    (_theme: Theme) => {
      if (_theme !== theme) {
        setTheme(_theme)
      }
    },
    [setTheme, theme]
  )
  useEffect(() => {
    Taro?.onThemeChange?.(themeChange)
    Taro?.onLocaleChange?.(langChange)
    return () => {
      Taro?.offThemeChange?.(themeChange)
      Taro?.offLocaleChange?.(langChange)
    }
  }, [themeChange, langChange])

//应用：
return (
    <View style={{
      backgroundColor: theme === Theme.DARK ? '#000000' : '#FFFFFF'
    }}>
      <Text>{platform}</Text>
      <Text>{screenWidth} x {screenHeight}</Text>
    </View>
  );

多语言

基于`@jdtaro/plugin-intl`实现动态语言切换

import { useIntl } from '@jdtaro/plugin-intl/dist/api'
const intl = useIntl()
  /** 天 */
  const singleDay = intl.formatMessage({ id: 'jd_order_countDown_day' })
  /** 时 */
  const singleHour = intl.formatMessage({ id: 'jd_order_countDown_hour' })
  /** 分 */
  const singleMin = intl.formatMessage({ id: 'jd_order_countDown_min' })

老年版

通过JDMode.getTextMode()区分处理

Taro?.JDMode?.getTextMode?.().then(res => {
    console.log('~~~~>JDMode?.getTextMode', JSON.stringify(res))
    const age = res?.data
    if (age === Age.OLD || age === Age.NORMAL || age === Age.YOUNG) {
      setAge(age)
      setIsCareOld(age === Age.OLD)
    }
  })

无障碍

无障碍需对业务中的图片类型进行梳理并确认读取内容，在标签设置位置分别进行单独配置。

属性名	类型	说明
`ariaRole`	string	角色
`ariaLabel`	string	为元素提供一个可访问名称，通常用于没有可见文本说明的控件。
`ariaHidden`	boolean	指定元素是否对辅助技术隐藏。`true`表示隐藏，`false`表示可访问。
`ariaChecked`	boolean	用于复选框、开关等控件，标识当前是否被选中。
`ariaSelected`	boolean	指示元素是否处于选中状态，常用于选项卡、列表项等。
`ariaRoledescription`	string	为元素的`role`提供额外说明，帮助辅助技术进一步解释该元素的功能。

<View className={styles.gift_box} onClick={gotoGift} ariaRole="button" ariaLabel={GIFT_CONTENT}>
      <Gift className={styles.gift_img} color={iconColor} />
</View>

大屏大字适配

  const isBigScreen = useDeviceStore(state => state.isBigScreen)
  // 大屏时底部元素高度会变化
    if (isBigScreen) {
      setTimeout(() => {
        getFooterHeight()
      }, 2000)
    } else {
      getFooterHeight()
    }

// 获取字体大小设置
Taro.JDMode.getTextSize().then(res => {
  setIsBigFont(res?.data === 'LARGE' ? true : false)
})

换肤主题

useEffect(() => {
    setIconColor('var(--order-navigator-skin)')
    try {
      Taro.JDTheme.unstable_getPageCodeTheme({
        pageCode: 'ORDER',
      })
        .then(result => {
          if (result?.data?.isOpen && result?.data?.bgUrl) {
            setSkinBg(result?.data?.bgUrl)
            if (result?.data?.colorType) {
              if (result?.data?.colorType === 'LIGHT' || result?.data?.colorType === 'DARKMODE') {
                setIconColor('#ffffff')
              } else {
                setIconColor('#191919')
              }
            }
          }
        })
        .catch(error => {
          console.log('unstable_getPageCodeTheme', 'error==' + JSON.stringify(error))
        })
    } catch (error) {
      console.log('unstable_getPageCodeTheme1', 'error==' + JSON.stringify(error))
    }

    // 搜索框曝光
    tracker?.exposure({ event_id: 'OrderList_HeadExpo', params: { trafficmap_material_name: mta_search } })
  }, [theme])

spm、scm埋点流量地图

if (data?.guideSpmEvent?.spmId) {
      tracker.exposure({
        spm: data?.guideSpmEvent?.spmId,
        json_param: data?.guideSpmEvent?.jsonParam,
        scm: data?.scm,
      })
}

import { useTracker, ViewTrafficMap, useExposure } from '@hlfe/hl-tracker'
<ViewTrafficMap
            ref={closeRef}
            className={styles.repurchaseCloseView}
            onClick={handleRepurchaseCloseClick}
            aria-label={i18n.closeTitle || '关闭'}
            id="repurchase_close_view"
            trafficMapInfo={{
              event_id: 'repurchase_close_view',
              spm: commonTaroJsonData?.closeBtnEvent?.exSpm || '',
              json_param: '',
            }}>
            <Image
              className={styles.bigdayClose}
              src="https://m.360buyimg.com/mobilecms/jfs/t1/364969/21/9455/393/69393f1dFe2b8595e/af7c6d22287474e7.png"
            />
</ViewTrafficMap>

3.2 新架构稳定性挑战

动态化Taro框架在安卓及iOS平台的订单模块实现了首次大规模业务应用。订单核心页面业务复杂度高，触发场景多样，存在较高的业务稳定性风险。任何一个环节出现异常，均可能对前后端交易链路的稳定性造成影响。为此，订单模块采用技术灰度验证的方式，优先保障核心交易业务链路的稳定运行，随后逐步推进长尾业务场景的治理工作。在技术灰度验证过程中，我们识别并解决了部分崩溃、白屏等问题，对每个问题均进行了深入分析并彻底修复。

同时建立核心场景的业务监控与告警机制，确保能够及时发现并处理潜在问题。

export const reportOrderBusinessErrorToDra = async (
  scene: string,
  functionId: string = '',
  netWorkResultCode: string = '',
  extraMap: object,
  requestParam: string = '',
): Promise<void> => {
  const reportSwitch = (await getOrderCustomErrorReportSwitch) ?? false
  if (reportSwitch) {
    const currentPage = useDeviceStore.getState().currentPage || '';
    const orderSourceKey = PAGE_TO_ORDER_SOURCE_KEY_MAP[currentPage] || 'pages/orderNew/list/index';
    const url = orderSourceKey
    const exception = JSON.stringify({
      scene: scene,
      code: netWorkResultCode,
      resultCode: '',
      errorMsg: '',
      isTaro: '1',
      extraParams: {
        ...extraMap,
      },
    })
    const error = {
      errCode: getDraErrorCode(),
      errMsg: scene,
      errType: '2',
      functionId: functionId,
      url: url,
      occurTime: parseInt((new Date().getTime() / 1000).toString()),
      httpResp: netWorkResultCode,
      postData: requestParam,
      exception,
    }
    Taro.JDDRA.reportError(error)
  }
}

监控包含多维度覆盖，首屏耗时、接口耗时、白屏、Taro异常、Bundle下载、业务异常等关键指标。通过烛龙性能监控（监控首屏耗时、接口响应时间等关键指标）、自定义错误码上报（精准定位业务异常）、网络接口耗时监控（识别性能瓶颈）等手段，实现了对业务全链路的实时监控和预警。为快速发现和解决问题提供了有力支撑。

通过完善的监控体系可实时感知系统状态，快速发现并响应问题，确保当日闭环处理，避免问题积压。该机制突破了依赖版本发布修复问题的限制，提升响应速度和处理效率，降低业务风险和用户体验下降，保障系统稳定运行与持续优化。

3.3 业务数据一致性挑战

新代码与原生多端在埋点实现及数据上报方面存在差异，可能带来一定风险，这将直接影响业务数据的准确性与决策的有效性。若数据出现不一致，将无法准确评估新功能的业务成效，也无法开展有效的数据分析工作。

在技术灰度发布期间，我们通过引入试金石指标和埋点数据系统化对比机制，对关键业务指标进行实时监控和分析。对于差异度超过10%的业务样本，我们建立了标准化的排查流程，逐一进行深入分析，查找数据偏差的根本原因。通过代码逻辑的逐层比对和业务场景的复现，精准定位问题所在，并在确认无误后及时进行代码修正和上线部署。这一系列措施有效保障了埋点数据在不同环境和版本之间的一致性，提升了数据的准确性和稳定性。同时，数据的可追溯性和可对比性也得到了显著增强，为业务方在关键节点上的决策提供了坚实的数据支撑，进一步推动了数据驱动的精细化运营。

3.4 长尾问题系统化治理

在大规模重构过程中，难以确保所有细节一次性达到理想状态。为有效治理长尾细节问题，我们引入AI扫描，对入参进行对比分析，提前识别改造后接口的异常情况，并及时进行修正。同时，结合数据采样匹配、监控告警机制以及快速修复的闭环流程，确保功能的完整性与系统稳定性。

四、代码质量保障机制

一码三端改造项目由多团队借调人员组成虚拟团队，需通过代码评审、自测、测试验证、数据采样匹配和监控等手段，持续完善核心场景工作内容。

4.1 codeReview机制

订单项目共组织开展了30余场业务CodeReview评审会议，全面采用多角色协同参与的代码评审机制，以确保代码质量与业务逻辑的准确性。评审团队由多个关键角色组成，包括业务梳理人、开发人员、前端架构师、Taro研发工程师以及测试人员等，通过多方协作，从不同视角对代码进行深入分析与评估，提升整体开发效率与系统稳定性。此外，业务研发还对每项开发任务进行了重要性与复杂程度的标注，便于在评审前快速识别出需要重点关注的模块或功能，从而合理安排评审资源与时间。在评审过程中，所有提出的意见与建议均被详细记录，并形成标准化的评审文档，便于后续跟踪与优化，确保问题能够及时闭环处理，持续推动项目高质量交付。

4.2 eslint检测

通过“一套规范、全流程守护”的 ESLint 体系，使用京东前端统一规范，并结合 Taro 框架与订单业务的专项规则进行定制化配置，确保代码风格与业务逻辑高度契合。在开发流程中，我们通过 husky 与 lint-staged 工具，在代码提交前自动拦截不符合规范的更改，防止低质量代码进入版本控制。每周输出检测报告，对发现的问题进行分类统计与跟踪，推动问题闭环整改，持续优化代码质量。这一整套机制有效保障了在多人协作开发环境下，代码风格统一、问题前置识别、质量可控，为项目长期稳定运行打下坚实基础。

五、提效痛点及优化

5.1 工作量大：AI提效

充分利用AI，将mCube、TN代码以及部分原生代码高效地转换为Taro框架，是当前提升开发效率的重要手段。通过深入梳理和分析不同技术栈之间的文件结构规则、语法规范以及事件处理机制，建立一套标准化的转换机制，实现代码的自动化迁移与转换。这一过程不仅包括对各类组件、API调用方式的映射处理，还涵盖了事件绑定、生命周期函数、状态管理等关键环节的适配与优化。在完成自动转换后，再结合完善的自测流程进行质量兜底，确保转换后的代码在功能、性能和兼容性方面均达到预期标准。通过这一系列技术手段，显著提升了开发效率和测试效率，缩短了项目周期，降低了人力成本，为团队的持续交付能力提供了有力支撑。

5.2 高效协作机制

在提前规划好近期提测内容所需的所有开发工作、依赖项及协作机制后，每日站会需识别各条线路的开发风险点。如发现关键问题可能影响排期，应立即进行调整，以确保研发资源与测试时间得到充分合理利用。同时，需协调技术改造与业务需求同步推进的时间节奏，首先明确改造工作的截止版本，并及时记录该版本之后识别出的新增业务改造点。改造完成后，同步推进需求追齐任务，同时由业务开发人员协同开发一码多端代码，确保各项需求能够及时跟进，避免进度滞后。

5.3 平台工具效率提升

订单模块首次进行鸿蒙包的集成打包，整体耗时8小时。首次打包耗时较长，主要由于团队对整体打包流程尚不熟悉，同时操作流程本身较为复杂。从Deco平台构建、预发发布、线上发布、本地编译、内置包配置、缺省逻辑处理、编译、Har包生成到最终集成，整个流程环节众多，操作繁琐。在平台前期建设阶段，构建流程同样存在较高的复杂度。针对多Bundle编译命令繁多、无法批量发布多端等影响效率的问题，订单团队与平台方积极沟通，共同制定提效方案。目前，相关流程已实现显著优化，编译、发布及内置等环节的效率均提升了一倍以上。