钉钉小程序跨端开发：一套业务两套代码架构实践

1. 钉钉小程序跨端开发实战：一套业务两套代码的架构设计

作为企业内部应用开发的热门平台，钉钉小程序在实际落地时经常面临一个关键问题：如何同时适配移动端和PC端的不同使用场景？最近我在开发一个内部审批系统时，就遇到了这个典型挑战。经过多次尝试和调整，最终采用了"一套业务逻辑，两套前端实现"的解决方案。下面分享具体实现过程和踩坑经验。

2. 项目背景与核心需求

我们需要开发一个请假审批系统，要求：

• 移动端通过钉钉小程序访问
• PC端通过浏览器访问同一业务系统
• 数据存储和业务逻辑完全统一
• 用户在不同终端体验一致

这种需求在OA类应用中非常典型——员工在外用手机提交申请，主管在办公室用电脑审批。看似简单的需求，在钉钉生态中却存在一些特殊的适配问题。

3. 钉钉应用创建的关键配置

3.1 创建企业内部应用

在钉钉开发者后台（https://open.dingtalk.com）创建应用时，有几个关键选择需要注意：

1. 应用类型：必须选择"企业内部应用"
2. 开发方式：选择"小程序"
3. 应用能力：务必勾选"小程序"能力

重要提示：如果漏选小程序能力，后续将无法正确配置跨端访问行为。这是我们第一个版本遇到的坑——当时只勾选了H5微应用，导致PC端访问异常。

3.2 PC端支持的特殊配置

钉钉后台的"开发管理"页面有几个影响PC端访问的关键配置项：

1. 是否支持PC端：这个选项控制着工作台搜索结果的跳转行为

   • 选择"是"时：
     • 工作台搜索打开 → 钉钉内打开小程序
     • 个人最近使用打开 → 浏览器打开配置的PC地址
   • 选择"否"时：
     • 所有入口统一在钉钉内打开小程序

2. PC端应用地址：必须填写完整的HTTP/HTTPS地址

   • 格式示例：https://your-domain.com/pc-entry
   • 不填写时会出现诡异行为（后文详述）

4. 不同配置下的行为差异实录

通过多次测试，我们记录了各种配置组合下的实际表现：

最危险的是第二种情况——当勾选支持PC但未填写地址时：

1. 用户从工作台搜索打开会直接跳转到钉钉官网
2. 从最近使用记录打开却能正常使用小程序
3. 这种不一致性会导致严重的用户体验问题

5. 技术架构设计与实现

5.1 整体架构方案

我们最终采用的方案架构如下：

code复制[后端API服务]
  ↑      ↑
[钉钉小程序] [PC端Web应用]

• 后端：统一的Spring Boot服务，提供RESTful API
• 移动端：钉钉小程序（基于DD MiniProgram框架）
• PC端：Vue.js + Element UI的Web应用

5.2 关键实现细节

5.2.1 用户认证方案

javascript复制// 小程序端认证
dd.getAuthCode({
  success: (res) => {
    const code = res.authCode;
    // 用code换取用户身份
  }
});

// PC端认证（OAuth2.0授权码模式）
window.location.href = `https://oapi.dingtalk.com/connect/oauth2/sns_authorize?
  appid=${appId}&
  response_type=code&
  scope=snsapi_auth&
  state=STATE&
  redirect_uri=${encodeURIComponent(redirectUri)}`;

5.2.2 跨端样式适配

由于两套前端代码，我们建立了统一的样式规范：

1. 颜色系统：使用CSS变量定义主色/辅助色

css复制:root {
  --primary-color: #1890ff;
  --success-color: #52c41a;
}

2. 间距系统：采用4px基准的间距体系

scss复制$spacer: 4px;

@function space($multiplier) {
  @return $spacer * $multiplier;
}

6. 开发中的典型问题与解决方案

6.1 PC端扫码登录难题

问题现象：

• PC端需要扫码登录，但测试环境没有外网域名
• 钉钉OAuth2.0要求备案域名

解决方案：

1. 开发阶段使用内网穿透工具（如ngrok）
2. 配置测试环境的回调白名单
3. 正式环境使用已备案域名

6.2 小程序与PC端API兼容

问题现象：

• 小程序要求HTTPS且域名备案
• PC端本地开发使用HTTP

解决方案：

javascript复制// API客户端封装
const baseURL = process.env.NODE_ENV === 'development' 
  ? 'http://localhost:8080/api'
  : 'https://api.your-domain.com';

const request = (url, options) => {
  return fetch(`${baseURL}${url}`, options);
};

7. 性能优化实践

7.1 小程序端优化

1. 分包加载：

json复制{
  "subPackages": [{
    "root": "subpackageA",
    "pages": ["pages/subA/index"]
  }]
}

2. 数据预取：

javascript复制Page({
  onLoad() {
    this.preloadData();
  },
  preloadData() {
    // 提前加载下一页数据
  }
});

7.2 PC端优化

1. 接口缓存：

javascript复制const cache = new Map();

const cachedRequest = async (url) => {
  if (cache.has(url)) {
    return cache.get(url);
  }
  const data = await request(url);
  cache.set(url, data);
  return data;
};

2. 虚拟滚动：

vue复制<template>
  <el-table
    :data="tableData"
    height="500"
    row-key="id"
    :row-height="60">
  </el-table>
</template>

8. 部署与发布流程

8.1 小程序发布

1. 开发版本 → 体验版本 → 审核 → 发布
2. 每次更新需要重新提交审核
3. 支持灰度发布（按部门/人员）

8.2 PC端部署

采用Docker容器化部署：

dockerfile复制FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

Nginx配置关键点：

nginx复制location / {
  try_files $uri $uri/ /index.html;
  gzip on;
}

9. 监控与异常处理

9.1 前端监控体系

1. 小程序错误监控：

javascript复制App({
  onError(err) {
    dd.httpRequest({
      url: '/log/error',
      data: { error: err.stack }
    });
  }
});

2. PC端性能监控：

javascript复制import { init } from '@aliyun-sls/web-rum';

init({
  pid: 'your-project-id',
  page: 'your-page'
});

9.2 后端日志收集

使用ELK栈：

• Elasticsearch 存储日志
• Logstash 处理日志
• Kibana 可视化

关键日志字段：

code复制timestamp, userId, deviceType, apiPath, responseTime, statusCode

10. 项目经验总结

经过这个项目的实践，有几个关键经验值得分享：

1. 环境隔离：开发/测试/生产环境要严格隔离，特别是钉钉回调地址配置
2. 用户引导：PC端和小程序端要有明确的使用引导，避免混淆
3. 设计系统：建立统一的设计规范库，保证两端体验一致
4. 埋点规划：前期就要设计好埋点方案，方便后续数据分析

实际开发中，我们还发现钉钉在不同客户端的一些细微差异：

• iOS和Android的小程序API有时表现不一致
• 钉钉Mac版和Windows版的窗口管理方式不同
• 企业微信等其他平台可能需要额外适配

这些经验让我们在后续项目中节省了大量调试时间。对于需要跨端支持的企业应用，这种"一套业务两套前端"的架构虽然初期投入较大，但长期来看更利于各端的体验优化和独立迭代。