企业官网建设流程全解析

1. 从一次接口联调翻车说起：Ajax 异步数据传输到底在解决什么问题

做前端开发的人，几乎都经历过这样的场景：页面填了一堆表单，点提交按钮，整个页面白屏转圈，等了三五秒才跳转，用户在这期间什么都干不了。更糟的是，如果后端返回一个错误，整个页面已经刷新了，用户填的内容全丢了，只能从头再来一遍。这种体验在十几年前是常态，而 Ajax 异步数据传输的出现，本质上就是为了干掉这种“整页刷新”的粗暴交互模式。

Ajax 全称 Asynchronous JavaScript and XML，直译过来就是“异步的 JavaScript 和 XML”。名字里虽然带着 XML，但实际发展到今天，绝大多数场景传输的都是 JSON 格式的数据，XML 反而成了少数派。它的核心价值在于：浏览器可以在不刷新整个页面的前提下，偷偷在后台跟服务器交换数据，拿到结果后只更新页面上的某一块区域。用户感觉不到页面跳转，操作是连续的、流畅的。

这个能力解决的核心问题有三个。第一是用户体验，局部刷新代替整页刷新，操作不中断。第二是性能开销，只传输需要的数据，而不是把整个 HTML 页面重新拉一遍，带宽和服务器压力都小很多。第三是前后端职责分离，后端只负责提供数据接口，前端负责渲染，两边可以并行开发，接口约定好就能各干各的。

适合看这篇内容的人，我大致分三类。一类是刚入门前端、对 Ajax 只有模糊概念的新手，知道要用但说不清楚原理；一类是工作一两年、天天写 Ajax 请求但没系统梳理过的开发者，想把这套东西的细节补齐；还有一类是后端或者全栈，需要跟前端对接接口，想搞清楚前端到底是怎么发请求、怎么处理编码、怎么传参数的。不管你属于哪一类，下面这些内容都是我在实际项目里踩过坑、调过 bug 之后沉淀下来的，不是照本宣科的文档搬运。

2. Ajax 异步数据传输的整体设计与核心思路拆解

2.1 为什么是“异步”：同步与异步的本质区别

要理解 Ajax，先得把“同步”和“异步”这两个词掰扯清楚。很多人第一次听到“异步”会觉得玄乎，其实用生活场景一类比就明白了。

同步请求就像你去银行柜台办业务，取号、排队、坐到窗口前，柜员处理你的业务期间，你只能干等着，什么都不能做，直到业务办完你才能离开。对应到浏览器里，就是发起一个请求后，整个页面被“锁住”，用户点任何按钮都没反应，必须等服务器返回结果，页面才能继续。

异步请求则像你在餐厅点完菜，服务员记下菜单就去后厨了，你该聊天聊天、该喝水喝水，菜做好了服务员再端上来。浏览器发起 Ajax 请求后，JavaScript 引擎不会停下来等结果，而是继续执行后面的代码，等服务器数据回来了，再通过回调函数或者 Promise 去处理。这就是“不阻塞”的含义。

这个区别带来的直接后果是：同步请求写起来简单，代码是一行一行顺序执行的，但体验差；异步请求体验好，但代码的执行顺序不再是线性的，需要理解回调、Promise、async/await 这些处理异步的机制。新手最容易犯的错，就是在 Ajax 请求后面直接写依赖返回数据的代码，结果请求还没回来，后面的代码已经跑完了，拿到的自然是空值。

2.2 一次完整 Ajax 请求的生命周期

一个 Ajax 请求从发起到拿到数据，中间经历了好几个阶段，理解这些阶段对排查问题特别有用。以最经典的 XMLHttpRequest 为例，它有一个 readyState 属性，取值从 0 到 4，分别代表不同的状态。

实际开发中我们最关心的是 readyState 变成 4 的时候，这时候再结合 HTTP 状态码判断请求是否成功。状态码 200 到 299 之间算成功，304 表示走缓存，400 以上基本就是出问题了。很多人只判断 readyState 不判断 status，结果服务器返回 500 错误页面，代码还傻乎乎地当成成功去解析，自然报一堆莫名其妙的错。

现在的开发中，XMLHttpRequest 基本被 fetch 和 axios 取代了，但底层原理没变，fetch 返回的 Promise 也是在请求完成后才 resolve，理解了这个生命周期，用哪个库都不会迷糊。

2.3 方案选型：XMLHttpRequest、fetch 还是 axios

这是新手问得最多的问题之一，我直接给结论：新项目无脑用 axios，学习原理用 fetch，维护老代码才碰 XMLHttpRequest。

XMLHttpRequest 是元老，兼容性最好，但 API 设计反人类，回调嵌套深了就是“回调地狱”，写起来痛苦。fetch 是浏览器原生提供的，基于 Promise，语法干净，但它有几个坑：默认不带 cookie、不会自动 reject 非 2xx 状态码、不支持超时控制，这些都得自己封装。axios 是第三方库，把 fetch 的那些坑都填了，还支持请求/响应拦截器、自动转换 JSON、取消请求、并发控制，是目前工程化项目里的主流选择。

选型的时候还要考虑项目环境。如果是简单的静态页面，不想引入额外依赖，fetch 够用。如果是 Vue、React 这类框架项目，axios 几乎是标配，配合拦截器统一处理 token、错误提示，能省很多重复代码。至于 XMLHttpRequest，除非你要兼容非常老的浏览器，否则没必要主动选它。

3. 核心细节解析与实操要点：编码、参数、接口调用

3.1 Ajax 请求设置编码格式：为什么中文会乱码

编码格式这个问题，是实际项目里翻车频率最高的点之一。我见过太多次前端传了中文参数，后端收到的是一堆问号或者乱码，两边互相甩锅。根子就在编码格式没对齐。

Ajax 请求涉及编码的地方主要有两处。第一处是请求体的编码，也就是 Content-Type 头。常见的取值有几种：

• application/x-www-form-urlencoded：表单默认格式，参数用key=value&key2=value2拼接，中文会被 URL 编码成%E4%BD%A0这种形式。
• application/json：现在最常用的格式，请求体是 JSON 字符串，需要保证字符串本身是 UTF-8 编码。
• multipart/form-data：上传文件时用，每个字段有独立的分隔符。
• text/plain：纯文本，很少用。

第二处是 URL 查询参数的编码。如果参数直接拼在 URL 上，比如?name=张三，浏览器会自动做 URL 编码，但不同浏览器、不同库的处理方式可能不一致，稳妥的做法是自己用encodeURIComponent处理一遍。

注意：用application/x-www-form-urlencoded时，如果参数里有特殊字符（比如&、=、+），必须做 URL 编码，否则参数会被截断或者解析错误。+在 URL 编码里代表空格，如果参数本身要传加号，得编码成%2B。

实操中最省心的做法是：统一用application/json，让 axios 自动序列化，后端也统一按 UTF-8 解析。这样中文乱码问题基本不会出现。如果后端接口强制要求表单格式，那就用qs库或者URLSearchParams来序列化，别自己手拼字符串。

3.2 给 Ajax 请求参数赋值：几种常见姿势和坑

参数赋值看起来简单，其实门道不少。我按场景分几种情况说。

GET 请求传参，参数拼在 URL 后面。用 axios 的话，直接写在params对象里，它会自动帮你拼到 URL 上并做编码：

axios.get('/api/user', { params: { id: 123, name: '张三' } })

POST 请求传参，参数放在请求体里。用 axios 默认就是 JSON 格式：

axios.post('/api/user', { id: 123, name: '张三' })

这里有个坑：如果你传的参数是一个对象或者数组，JSON 序列化没问题，但如果后端期望的是表单格式，就得用qs.stringify转换一下，并且把 Content-Type 设成application/x-www-form-urlencoded。

动态赋值的场景也很常见，比如从表单里读值。这时候要注意类型转换，表单读出来的值默认都是字符串，如果后端期望数字，得用Number()或者parseInt转一下，否则可能触发类型校验失败。

还有一个容易被忽略的点：参数值为 undefined 或 null 时的处理。axios 默认会把值为 undefined 的字段直接忽略，不拼进请求里；而 null 会被序列化成null字符串。如果后端对字段存在性敏感，这个差异会导致问题。我的习惯是，传参前统一过滤一遍，把 undefined 和空字符串都处理掉，保证传给后端的参数是干净的。

3.3 泛微 ecology9 中 Ajax 调用后端接口的实践

泛微 ecology9 是国内用得很多的一套协同办公平台，它的前端页面里大量使用 Ajax 跟后端接口交互。跟普通前后端分离项目不同，ecology9 有自己的接口规范和鉴权机制，直接照搬通用写法容易碰壁。

在 ecology9 里调后端接口，通常走的是它封装的jQuery.ajax，因为平台本身依赖 jQuery。请求的 URL 一般是/api/开头的路径，鉴权靠的是登录后写入的 cookie 或者请求头里的 token。这里有几个实操要点。

第一，接口路径要对。ecology9 的接口分好几种，有标准的 REST 接口，也有自定义的 action。路径写错了，返回的可能是登录页的 HTML，而不是 JSON，前端解析就会报错。判断方法很简单，看返回的 Content-Type，如果是text/html而不是application/json，八成是路径或者鉴权出了问题。

第二，参数格式要匹配。ecology9 的部分接口期望的是表单格式，而不是 JSON。这时候就得用$.ajax的contentType: 'application/x-www-form-urlencoded'，并且用$.param()序列化参数。

第三，跨域和同源。ecology9 部署在内网，前端页面和接口通常同源，一般不会有跨域问题。但如果做了前后端分离改造，就得让后端配置好跨域头，否则请求会被浏览器拦截。

$.ajax({ url: '/api/ecology/user/getUserInfo', type: 'POST', contentType: 'application/x-www-form-urlencoded; charset=UTF-8', data: $.param({ userId: 123 }), success: function(res) { if (res.code === 200) { console.log(res.data); } }, error: function(xhr) { console.error('请求失败', xhr.status); } });

提示：ecology9 的接口返回结构通常是{ code, data, msg }这种形式，code 为 200 才算成功。别只看 HTTP 状态码，业务层面的错误码也要判断。

4. 实操过程与核心环节实现：从零搭一个异步请求

4.1 环境准备与基础封装

我以一个实际项目里常用的封装为例，走一遍完整流程。假设我们用 axios，先装依赖：

npm install axios

然后建一个request.js，做统一封装。为什么要封装？因为项目里几十上百个接口，如果每个都写一遍 baseURL、超时、token 注入、错误处理，重复代码太多，改起来也痛苦。封装一次，全局受益。

import axios from 'axios'; const service = axios.create({ baseURL: '/api', timeout: 10000, headers: { 'Content-Type': 'application/json;charset=UTF-8' } }); // 请求拦截器：统一注入 token service.interceptors.request.use( config => { const token = localStorage.getItem('token'); if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }, error => Promise.reject(error) ); // 响应拦截器：统一处理错误 service.interceptors.response.use( response => { const res = response.data; if (res.code !== 200) { console.error('业务错误：', res.msg); return Promise.reject(new Error(res.msg)); } return res.data; }, error => { if (error.response) { console.error('HTTP错误：', error.response.status); } return Promise.reject(error); } ); export default service;

这段代码里，baseURL统一了接口前缀，timeout防止请求一直挂着，请求拦截器自动带 token，响应拦截器统一判断业务码。这样业务代码里调接口就非常干净：

import request from './request'; export function getUserInfo(userId) { return request.get('/user/info', { params: { userId } }); }

4.2 参数计算与编码处理的实际操作

前面讲了编码的理论，这里给一个实际处理的例子。假设后端要求表单格式，参数里有中文和特殊字符，我们这样处理：

import qs from 'qs'; const params = { name: '张三', remark: 'a+b=c&d', age: 25 }; const data = qs.stringify(params, { encode: true, charset: 'utf-8' }); // 结果：name=%E5%BC%A0%E4%B8%89&remark=a%2Bb%3Dc%26d&age=25

qs.stringify会自动把中文和特殊字符做 URL 编码，+变成%2B，=变成%3D，&变成%26，这样后端解析的时候就不会出错。如果不用qs，用原生的URLSearchParams也行：

const usp = new URLSearchParams(); usp.append('name', '张三'); usp.append('remark', 'a+b=c&d'); usp.append('age', 25); const data = usp.toString();

两种方式效果差不多，qs对嵌套对象的支持更好，URLSearchParams是原生 API 不用装依赖。选哪个看项目情况。

4.3 异步流程控制：Promise 与 async/await

Ajax 是异步的，处理异步结果的方式从早期的回调，到 Promise，再到 async/await，越来越接近同步代码的写法。我强烈建议新代码一律用 async/await，可读性比 then 链好太多。

async function loadUserData(userId) { try { const userInfo = await getUserInfo(userId); const orderList = await getOrderList(userInfo.id); renderPage(userInfo, orderList); } catch (err) { console.error('加载失败', err); } }

这里有个细节：await后面跟的必须是 Promise，如果跟的是普通值，会直接返回。另外，多个没有依赖关系的请求，不要傻乎乎地一个个 await，那样是串行的，慢。用Promise.all并发：

const [userInfo, orderList] = await Promise.all([ getUserInfo(userId), getOrderList(userId) ]);

这样两个请求同时发出，总耗时取决于最慢的那个，而不是两个相加。这个优化在接口多的时候效果非常明显，我做过一个页面，串行请求要 2 秒多，改成并发后 800 毫秒就出来了。

5. 常见问题与排查技巧实录

5.1 请求发出去了但拿不到数据：排查思路

这是最高频的问题，我整理了一个排查顺序，按这个走基本能定位。

我遇到最多的情况是 401，token 过期了但前端没处理，请求一直失败。解决办法是在响应拦截器里统一判断 401，跳转登录页或者刷新 token。还有一种情况是返回了数据但前端拿不到，仔细一看是响应拦截器里return res.data写成了return res，业务代码里又按res.data取，自然取不到。

5.2 跨域问题的本质与解决方向

跨域是另一个绕不开的话题。浏览器的同源策略规定，协议、域名、端口三者只要有一个不同，就算跨域，Ajax 请求会被拦截。注意，请求其实发出去了，服务器也响应了，只是浏览器不让前端代码拿到响应内容。

解决跨域的方向有两个。一是后端配置 CORS 头，允许特定来源访问，这是最正规的做法。二是前端通过开发服务器的代理转发，把请求先发到同源的开发服务器，再由它转发到真实后端，这样浏览器看来就是同源请求。Vue CLI 和 Vite 都支持配代理：

// vite.config.js export default { server: { proxy: { '/api': { target: 'http://backend-server:8080', changeOrigin: true, rewrite: path => path.replace(/^\/api/, '') } } } }

注意：代理只在开发环境有效，生产环境还是得靠后端配 CORS 或者用 Nginx 做反向代理。别以为开发环境跑通了就万事大吉。

5.3 那些文档里不会写的避坑经验

说几个我踩过的坑，都是文档里不会提但实际很坑人的。

第一个，GET 请求带缓存。某些浏览器对 GET 请求会缓存，同样的 URL 第二次不发请求直接返回缓存。如果接口数据是实时的，就会拿到旧数据。解决办法是在 URL 后面加时间戳或者随机数，或者让后端设置Cache-Control: no-cache。

第二个，请求重复提交。用户手快点了两次提交按钮，发了两个请求，后端创建了两条数据。解决办法是提交时禁用按钮，或者用取消令牌把前一个请求取消掉。axios 支持CancelToken，可以做到。

第三个，大文件上传超时。默认超时时间设太短，上传大文件时请求还没传完就超时了。这种情况要单独给上传接口设更长的超时，或者用分片上传。

第四个，并发请求过多。页面初始化时一口气发几十个请求，浏览器对同域名并发数有限制（通常 6 个），超出的会排队，反而更慢。合理做法是合并接口，或者分批加载。

6. 异步数据传输的进阶玩法与性能优化

6.1 请求取消与防抖节流

搜索框输入联想是 Ajax 的经典场景，但用户每敲一个字就发一次请求，既浪费又可能因为响应顺序错乱导致显示错误结果。这时候需要防抖：用户停止输入 300 毫秒后才发请求。

function debounce(fn, delay) { let timer = null; return function(...args) { clearTimeout(timer); timer = setTimeout(() => fn.apply(this, args), delay); }; } const search = debounce(async function(keyword) { const result = await request.get('/search', { params: { keyword } }); renderSuggestions(result); }, 300);

防抖解决的是“发太频繁”，请求取消解决的是“发了但不要了”。axios 的CancelToken或者新版的AbortController都能做到。用户输入新关键词时，把上一个还没返回的请求取消掉，避免旧结果覆盖新结果。

6.2 数据缓存减少重复请求

有些数据不常变，比如字典表、配置项，每次进页面都请求一遍没必要。可以在前端做一层缓存，用 Map 存起来，下次直接用。或者用 HTTP 缓存，让后端返回ETag或Last-Modified，浏览器自动判断是否走缓存。

我一般会在请求层加一个简单的内存缓存，针对特定接口开启：

const cache = new Map(); async function getWithCache(url, params) { const key = url + JSON.stringify(params); if (cache.has(key)) { return cache.get(key); } const data = await request.get(url, { params }); cache.set(key, data); return data; }

缓存要注意失效策略，数据更新后要清掉对应的缓存，否则用户看到的是旧数据。简单做法是设置过期时间，复杂点就靠发布订阅，数据变更时主动清缓存。

6.3 从 Ajax 到更现代的交互模式

Ajax 解决了异步通信的问题，但页面交互越来越复杂，单纯靠 Ajax 手动更新 DOM 已经不够用了。于是有了前端框架，Vue、React 这些把数据绑定和视图更新自动化了，开发者只需要关心数据，视图自动跟着变。再往后，WebSocket 解决了服务器主动推送的问题，SSE 解决了单向流式推送的问题，各有各的适用场景。

但不管上层怎么变，底层的异步数据传输机制还是那套东西。理解了 Ajax 的本质，学框架、学新协议都会快很多。我见过不少新手直接上手 Vue，用 axios 发请求，但说不清楚请求是怎么发出去的、数据是怎么回来的，遇到问题就抓瞎。把基础打牢，上层的东西才学得扎实。

最后分享一个我个人的习惯：每次调接口出问题，先打开 Network 面板，把请求的 URL、方法、请求头、请求体、响应头、响应体完整看一遍，九成的问题都能在这一步定位。别急着改代码，先看清楚数据到底长什么样，比盲目试错高效得多。