企业官网建设流程全解析

线上教学平台里，视频播放这一类需求看着简单，真到联调阶段往往最容易卡壳。前段时间帮一个做在线课程的朋友排查问题，用户在课程详情页点开某个小节，播放器区域转圈圈，控制台里那条获取播放凭证的请求长得特别刺眼——URL 末尾干干净净，/eduvod/video/getPlayAuth/后面什么都没有。后端日志里videoId打印出来是null，云端接口自然返回参数错误。这就是很典型的一类故障：获取视频播放凭证时拿不到 video.Id。它表面上是一个参数没传过去，实际上牵扯到前端传参、雪花 ID 精度、后端注解绑定、网关路由转发、数据库字段类型、上传回填链路这六七个环节，任何一个环节掉链子，症状都是同一个。这篇文章我打算把这条链路从头到尾拆一遍，讲清楚 videoId 在这套系统里到底从哪来、往哪去、为什么会丢，再给出一套可以直接照着改的修复方案和排查清单。不管你是刚接手这类项目的新手，还是已经写过几遍播放模块、但每次都被 ID 问题绊一下的老手，应该都能从里面捞到点东西。

1. 先把播放链路还原：videoId 在这套系统里到底扮演什么角色

1.1 一条播放请求的完整生命周期

要看懂这个报错，得先知道用户点下播放按钮之后，系统里到底发生了什么。这套在线教育平台的视频并不是存在自己服务器上的，而是上传到云端视频点播服务，由云端负责存储、转码、分发和加密播放。课程发布阶段，讲师在后台上传视频，前端先向业务后端申请上传地址和上传凭证，拿到之后把视频文件直传到云端；云端处理完成后会返回一个全局唯一的视频 ID，这个 ID 就是后面播放凭证的唯一钥匙。业务后端会把这个 ID 落到课程小节表里，字段名一般叫video_source_id，跟小节自身的主键 ID 是两个完全不同的东西。

用户播放阶段是反过来的。课程详情页点开某个小节，前端跳转到播放页，播放页在created生命周期里发起一次请求，把视频 ID 拼到 URL 路径上，请求业务后端/eduvod/video/getPlayAuth/{videoId}。业务后端拿到这个 ID，调用云端 SDK 的播放凭证接口，云端校验 ID 合法性、校验账号权限、校验视频状态，然后签发一个有效期很短的加密串，也就是 playAuth。前端拿到 playAuth，再配合 videoId 一起交给播放器 SDK，播放器才能解密拉流。

整条链路里，videoId 是那个"一夫当关"的角色。它为空，后端调云端接口直接抛参数异常；它被截断，云端返回"视频不存在"；它传错了对象，比如把小节主键当成了视频源 ID，云端同样不认识。所以排查这类问题时，第一步不是急着改代码，而是把这条链路画出来，确认断点到底在哪一环。

1.2 videoId 和 videoSourceId：最容易混淆的一对字段

我在帮人看这类问题时，十次里有三四次是字段搞混了。课程小节表里通常至少有两个 ID：一个是表主键id，雪花算法生成，19 位纯数字；另一个是video_source_id，云端返回的字符串，通常三十多位，字母数字混合。前端在课程详情页渲染章节列表时，两个字段都拿到了，但点击播放时到底该传哪个，很多人在写的时候是随手抓的。

正确的做法是：跳转播放页和请求播放凭证，用的必须是video_source_id，而不是小节主键。主键是用来做增删改查定位记录的，云端根本不认识它。我曾经见过一个版本，前端把id传过去了，后端也没做校验，直接透传给云端，云端返回"视频不存在"，然后前端弹了个"获取播放凭证失败"，排查了一下午才发现传的是主键。更隐蔽的情况是列表接口做了字段裁剪，只返回了id和标题，把video_source_id给漏了，前端拿不到就只能传空，于是出现了标题里那个现象。

1.3 为什么这个参数一空，后面全盘皆输

有人会问，参数为空后端加个判空返回友好提示不就行了，为什么还要大动干戈。问题在于，播放凭证接口是整条播放链路的第一道闸门，它失败了，后面的播放器初始化、进度上报、观看时长统计、学习记录写入全部不会触发。从用户视角看就是"视频打不开"，从运营视角看就是"这个学员的学习进度卡住了"，从数据视角看就是观看时长统计出现空洞。

更麻烦的是这类问题的复现条件不稳定。开发环境数据少、ID 短，可能一直正常；上了测试环境，雪花 ID 变成 19 位，前端精度一丢，问题就冒出来了。所以我的态度一直是：不要把它当成一次偶发的参数丢失来修，要把它当成一类系统性的 ID 传递问题来治，前端、后端、数据库、网关四层一起过一遍，才算修干净。

2. 为什么偏偏是 video.Id 拿不到：四层原因逐层拆解

2.1 前端传参层：变量没值、拼接失败、刷新丢失

最直接的一层原因在前端。播放页拿 videoId 通常有三个来源：路由 params、路由 query、状态管理或本地存储。三种方式各有各的坑。路由 params 方式在页面刷新后会丢失，因为刷新时浏览器只认 URL，params 不体现在地址栏里，一刷新this.$route.params.videoId就是 undefined。路由 query 方式会体现在地址栏，刷新不丢，但拼接时如果变量本身是 undefined，URL 里就会出现字面量undefined，后端收到的是字符串 "undefined"，判空判不掉，直接透传给云端，报一个莫名其妙的错误。

还有一种常见情况是异步时序问题。课程详情页点击小节时，先发请求查小节详情，再跳转播放页。如果跳转写在请求回调外面，或者没有等 Promise 完成，跳转时详情数据还是空的，videoSourceId自然取不到。这类 bug 在本地跑很快的时候不容易发现，网络一慢就必现。

再就是接口封装层的参数位置写错了。有的项目里getPlayAuth方法定义成getPlayAuth(params)，内部用params: { videoId }走 query 传参，但后端接口签名是@PathVariable，两边对不上，后端收到 null。这种错误不会报编译错，只能靠抓包发现。

2.2 精度层：19 位雪花 ID 在浏览器里被悄悄改写

这是我认为最值得单独拎出来讲的一层，也是很多新手完全没意识到的坑。JavaScript 的 Number 类型底层是双精度浮点数，能精确表示的整数上限是 2 的 53 次方减一，也就是 9007199254740991，一共 16 位。而雪花算法生成的 ID 是 19 位。当后端把 19 位的 Long 型 ID 以 JSON 数字形式返回给前端，前端JSON.parse的时候就会发生精度丢失，后几位被四舍五入。

举个具体例子，后端返回1791234567890123456，前端拿到手可能变成1791234567890123500。这个值再传回后端，数据库里查不到，云端更查不到。症状表现就是：请求发出去了，参数看着也有值，但就是查不到视频，或者报"视频不存在"。更坑的是有些 ID 末位恰好是 0，丢失精度后数值不变，于是同一个系统里一部分视频能播、一部分不能播，排查起来极其迷惑。

这个问题的根因不在前端也不在后端，而在两边对 Long 类型的序列化约定不一致。标准解法是后端全局把 Long 序列化成字符串输出，前端按字符串接收、按字符串传递，全程不经过 Number 运算。这一点我在第 3 节会给完整配置。

2.3 后端接收层：注解不匹配、路径被改写、网关截断

参数确实传到了后端，但没绑上，这也是一大类。Spring MVC 里路径变量用@PathVariable，查询参数用@RequestParam，请求体用@RequestBody，三者混用就会出问题。接口声明成@GetMapping("getPlayAuth/{videoId}")，方法参数却写成@RequestParam String videoId，启动时不报错，运行时绑定不上，拿到 null。反过来接口声明成getPlayAuth，前端却按路径拼接/getPlayAuth/123，直接 404。

路径变量名和注解里的名字不一致也会出问题。声明是{videoId}，注解写成@PathVariable("vid")，没有显式指定名称的情况下，某些编译配置下会拿不到值。稳妥的写法是注解里显式写名字，跟占位符一字不差。

微服务架构下还多一层网关。前端请求先到网关，网关按谓词匹配路由再转发到具体服务。如果路由配置里做了StripPrefix或者RewritePath，把路径前缀或者某一段剥掉了，转发到下游服务的路径就变了，@PathVariable自然绑不上。这种情况后端日志里能看到请求进来了，但参数是 null，很容易误判成前端没传。

2.4 数据来源层：小节表里压根就没有 videoSourceId

最后一层，也是最容易被忽略的一层：参数一路传得好好的，但数据库里那个字段本来就是空的。视频上传成功后，云端返回了 videoId，前端需要再调一次业务接口把这个 ID 回填到小节记录上。这一步如果漏了、失败了、或者被事务回滚了，video_source_id字段就是 null。播放页拿到 null，拼出来的 URL 就是空的。

还有一种情况是字段类型不对。早期建表时图省事，把video_source_id定义成int或者bigint，云端返回的字符串 ID 存进去要么报错，要么被截断，要么存成 0。等到播放时读出来是个无效值，问题就暴露了。这类历史遗留问题在新项目里少见，在老项目改造时特别多。

3. 从定位到修复：一份可以直接照着改的实操方案

3.1 五分钟定位：用浏览器和后端日志锁定断点

排查我一般按"看请求、看日志、看数据"三步走，基本五分钟能锁定断点。

第一步，浏览器 F12 打开 Network 面板，点播放，找到那条获取凭证的请求，重点看三处：请求 URL 长什么样、请求方法是 GET 还是 POST、响应体返回了什么。如果 URL 末尾是空的或者带着undefined，问题在前端；如果 URL 正常但后端返回参数为空，问题在网关或后端绑定；如果 URL 和参数都正常但返回业务错误，问题在数据或云端。

第二步，后端在接口入口加一行日志，把入参原样打出来。这一行日志的价值极高，它能明确告诉你请求到底有没有到、到了之后参数是什么。我习惯写成log.info("获取播放凭证，videoId={}", videoId);，简单直接。

第三步，拿这个 videoId 去数据库查。执行select id, video_source_id, title from edu_video where id = ?，看这个字段是不是空、长度对不对、跟云端返回的是不是同一个值。三步走完，问题落在哪一层基本就清楚了。

如果还想再快一点，可以用接口调试工具直接调后端接口，绕开前端。能通说明后端没问题，问题在前端传参；不能通说明后端或数据有问题。这一招在做前后端责任划分时特别好用。

3.2 前端修复：参数来源统一、路由传参规范

前端这块我的建议是"一个入口、一次校验、一路字符串"。先看接口封装：

// api/video.js import request from '@/utils/request' export default { // videoId 必须是字符串，禁止传数字 getPlayAuth(videoId) { return request({ url: `/eduvod/video/getPlayAuth/${videoId}`, method: 'get' }) } }

再看播放页的参数获取逻辑，核心是三点：多来源兜底、显式判空、强制转字符串。

data() { return { videoId: '', playAuth: '', player: null } }, created() { // 路由 params 优先，刷新丢失时回退到 query const rawId = this.$route.params.videoId || this.$route.query.videoId if (!rawId || rawId === 'undefined' || rawId === 'null') { this.$message.error('视频参数缺失，请返回课程详情页重新进入') return } this.videoId = String(rawId) this.fetchPlayAuth() }, methods: { fetchPlayAuth() { videoApi.getPlayAuth(this.videoId).then(res => { const { playAuth } = res.data.data if (!playAuth) { this.$message.error('播放凭证为空，请联系管理员') return } this.playAuth = playAuth this.initPlayer() }).catch(err => { console.error('获取播放凭证失败', err) this.$message.error('获取播放凭证失败，请稍后重试') }) }, initPlayer() { this.player = new cloudPlayer({ id: 'player-container', width: '100%', height: '500px', vid: String(this.videoId), playauth: this.playAuth }) } }

这里有几个细节值得说。判空的时候一定要把字符串'undefined'和'null'一起判掉，因为模板字符串拼接会自动把 undefined 转成字符串，这是最常见的漏网之鱼。vid传参必须强制String()，播放器 SDK 内部如果按数字处理，19 位 ID 一样会丢精度。跳转播放页时优先用 query 而不是 params，虽然地址栏会带一长串 ID 不太美观，但刷新不丢参数，稳定性远比美观重要。

从课程详情页跳转的代码也要规范：

playVideo(video) { if (!video.videoSourceId) { this.$message.warning('该小节暂未上传视频') return } // 用 query 传参，刷新不丢 this.$router.push({ path: '/player', query: { videoId: String(video.videoSourceId) } }) }

注意这里判断的是videoSourceId，传的也是videoSourceId，不是小节主键。这个字段名一定要跟后端返回的 JSON 字段对齐，前后端字段约定不一致是另一个高频问题。

3.3 后端修复：接口签名、参数校验、全局 Long 序列化

后端接口本身要写得"防呆"。签名用@PathVariable，注解里显式写变量名，入口处做判空和格式校验：

@GetMapping("getPlayAuth/{videoId}") public R getPlayAuth(@PathVariable("videoId") String videoId) { log.info("获取播放凭证，videoId={}", videoId); if (!StringUtils.hasText(videoId)) { return R.error().code(20001).message("视频ID不能为空"); } try { String playAuth = vodService.getPlayAuth(videoId); return R.ok().data("playAuth", playAuth); } catch (Exception e) { log.error("获取播放凭证异常，videoId={}", videoId, e); return R.error().code(20002).message("获取播放凭证失败"); } }

服务层调用云端 SDK 的部分，重点是异常分类和日志留痕：

@Override public String getPlayAuth(String videoId) { GetVideoPlayAuthRequest request = new GetVideoPlayAuthRequest(); request.setVideoId(videoId); request.setAuthInfoTimeout(3000L); try { GetVideoPlayAuthResponse response = client.getAcsResponse(request); return response.getPlayAuth(); } catch (ClientException e) { log.error("云端返回异常，videoId={}, code={}", videoId, e.getErrCode(), e); throw new BusinessException(20002, "视频不存在或已下架"); } }

然后是全局 Long 序列化配置，这一条是解决精度丢失的关键：

@Configuration public class JacksonConfig { @Bean public Jackson2ObjectMapperBuilderCustomizer longToStringCustomizer() { return builder -> { builder.serializerByType(Long.class, ToStringSerializer.instance); builder.serializerByType(Long.TYPE, ToStringSerializer.instance); }; } }

加上这段配置之后，所有 Long 类型的字段在 JSON 响应里都会输出成带引号的字符串，前端接收时天然就是 string，不会经过 Number 转换，精度问题一次性解决。如果不想全局改，也可以在实体字段上单独加@JsonSerialize(using = ToStringSerializer.class)，但字段多了容易漏，我还是推荐全局配置。

这里有个副作用要提前打招呼：全局配置之后，前端所有依赖数字类型做计算的地方都要跟着改，比如分页参数、状态值。所以这个配置最好在项目早期就加上，中途加要评估影响面。

3.4 数据修复：字段类型、上传回填链路、历史数据补录

数据库这块，video_source_id字段类型必须是varchar，长度给到 64 足够：

ALTER TABLE edu_video MODIFY COLUMN video_source_id VARCHAR(64) DEFAULT NULL COMMENT '云端视频ID';

然后检查上传回填链路。讲师上传视频的完整流程是：申请上传凭证、直传云端、拿到云端返回的 videoId、调业务接口保存到小节记录。最后这一步最容易断。我的做法是在保存接口里加事务和日志，保存成功后立即回查一次确认写入：

@Transactional(rollbackFor = Exception.class) public void saveVideoSourceId(String sectionId, String videoSourceId) { if (!StringUtils.hasText(videoSourceId)) { throw new BusinessException(20003, "视频源ID为空，拒绝写入"); } EduVideo video = new EduVideo(); video.setId(sectionId); video.setVideoSourceId(videoSourceId); boolean ok = this.updateById(video); if (!ok) { throw new BusinessException(20004, "视频源ID回填失败"); } log.info("视频源ID回填成功，sectionId={}, videoSourceId={}", sectionId, videoSourceId); }

历史数据补录就得靠人工或者脚本了。先查出来哪些小节有视频标题但没有视频源 ID：

SELECT id, title, video_source_id FROM edu_video WHERE video_source_id IS NULL OR video_source_id = '' ORDER BY id DESC;

然后对照云端控制台的视频列表逐条补。这个过程比较枯燥，但做过一次之后，把回填链路加上校验，后面就不会再出。

4. 常见问题速查与踩坑实录

4.1 症状对照表：二十秒锁定方向

把线上遇到过的现象整理成一张表，方便对照：

这张表我一般直接贴在项目文档里，新同事接手播放模块先看一遍，能省掉大量重复沟通。

4.2 几个只有踩过才知道的细节

第一个坑：模板字符串会吞掉类型。`${videoId}`在 videoId 为 undefined 时不会报错，会老老实实拼成字符串 "undefined"。所以判空一定要在拼接之前做，而不是依赖拼接结果。

第二个坑：ID 末位是 0 的雪花 ID 会掩盖精度问题。精度丢失是四舍五入，如果末几位本来就接近 0，丢失后数值不变，测试环境可能一直正常。我建议专门构造一批末位非零的测试数据来验证。

第三个坑：网关和后端服务的日志要对着看。有时候前端 URL 完全正确，网关日志里路径也对，但下游服务收到的是 null，这时候就要看网关有没有做参数过滤。application.yml里的StripPrefix、RewritePath配置，改一行就能让整条链路错位。

第四个坑：上传成功的回调可能比前端请求先到也可能后到。如果业务依赖回调去写视频源 ID，而用户上传完立刻点播放，就会读到空值。稳妥的做法是上传成功后前端主动调一次保存接口，回调只作为兜底。

第五个坑：播放器 SDK 初始化失败不一定是凭证问题。有时候 playAuth 拿到了，但vid传成了数字导致精度丢失，播放器同样报错。这一步排查时要把 vid 和 playauth 分开验证。

提示：排查任何"参数为空"类问题，永远先看请求原始 URL，不要先看代码。代码里写对了但实际请求错了的情况，比想象中多得多。

4.3 一套可复用的联调自检流程

我习惯在每次改完播放模块后走一遍这个自检：第一步，手动构造一条小节数据，video_source_id填一个真实有效的云端 ID；第二步，从课程详情页点击播放，抓包确认 URL 中 ID 与数据库一致；第三步，把 ID 复制出来逐字符对比，重点看末尾几位；第四步，刷新播放页，确认参数不丢；第五步，用接口工具直接调后端接口，确认后端独立可用；第六步，故意传一个空 ID，确认后端返回的是友好提示而不是 500。六步走完，这个模块的健壮性基本就有底了。

5. 防御性设计：让 videoId 类问题不再复发

5.1 接口层：入参校验与错误码约定

修好一次不算完，得让这类问题以后要么不发生，要么一发生就能快速定位。接口层的做法是把校验前移。所有接收 ID 的接口，入口第一件事就是判空和格式校验，不合法直接返回业务错误码，不要透传到云端。错误码要约定清楚，比如 20001 表示参数为空，20002 表示云端调用失败，20003 表示视频不存在。前端拿到不同错误码展示不同提示，用户看到的就不再是一句笼统的"操作失败"。

同时建议在接口文档里把参数类型写死成 string，并在文档里明确注明"禁止按数字处理"。这一条看起来啰嗦，实际能挡住很多后来者的手滑。

5.2 数据层：字段类型与回填时机

数据层的核心是两件事：字段类型正确、回填时机可靠。字段类型前面说过，统一varchar(64)，主键用 bigint 没问题，但所有参与前端传递的 ID 都要走字符串通道。回填时机上，我倾向"前端主动保存为主、云端回调兜底为辅"的双保险设计。前端上传成功后立刻调保存接口，失败时给出明确提示让用户重试；云端回调作为异步补偿，回调处理里做幂等判断，避免重复写入。

另外，小节记录保存时加一个数据库层面的约束会更稳，比如允许为空但不允许空字符串，通过应用层统一处理成 null，查询时只需要判IS NULL一种情况，逻辑更简单。

5.3 联调规范：前后端字段契约

最后说一个软性的东西：字段契约。前后端联调出问题，七成是字段名对不上或者类型理解不一致。我的建议是接口文档里把每个字段的名称、类型、是否必填、示例值都列清楚，尤其是 ID 类字段，示例值直接给一个 19 位字符串，让前端一眼看出这不是数字。前端在api层做一层薄封装，所有 ID 参数进来先String()一次，把类型风险挡在最外层。

我在实际项目里还加过一个小工具函数，专门用来处理这类参数：

export function safeId(value) { if (value === null || value === undefined) return '' const s = String(value).trim() if (s === '' || s === 'undefined' || s === 'null' || s === '0') return '' return s }

所有从路由、接口、本地存储取出来的 ID 都过一遍这个函数，取不到就返回空串，调用方统一按空串判空，逻辑统一，不容易漏。就这么一个十几行的函数，帮我们省掉了好几次深夜排查。

这类问题的本质，其实是分布式系统里"标识符"这个东西被低估了。它跨越了数据库、后端序列化、HTTP 传输、浏览器运行时、云端服务五个边界，每个边界都有自己的类型规则。把这些边界守住，标题里那个让人抓狂的空 videoId，也就不会再出现了。