Yore

十一节后工作日记

Fri, 09 Oct 2026 00:00:00 GMT

十一假期之后的第一项工作，是给智慧科协补一套运营位管理功能。需求看起来很集中：管理端配置移动端首页轮播图，移动端按配置展示图片，需要时再跳转到指定链接。

真正做下来，工作并没有停在“画一个列表，再放一个轮播组件”。页面需要延续旧系统的布局和交互，接口要接入现有网关与请求封装，上传后的图片还经历了临时文件、业务关联和 OSS 文件三个阶段。最后遇到的图片无法预览问题，也正是出在这些 ID 的语义没有分清。

这篇日记按最终保留下来的功能记录实现过程，也把接口阅读和文件链路多展开一些。

1. 先确定最终页面链路#

运营位管理的入口放在业务管理工作台中，位置紧跟科技馆人流监控统计。入口沿用工作台原有卡片结构，图标放在项目统一的资源目录中，尺寸、文字和悬停效果都由原组件控制。点击后进入独立的运营位管理路由。

最终页面只保留一项业务：移动端首页轮播图。页面分成筛选区、操作区、数据表格和分页区：

区域	功能
筛选区	图片标题、启用时间、启用状态
操作区	新增、批量删除
表格	标题、跳转类型、状态、启用时间、操作
行操作	启用/禁用、编辑、查看
分页	总数、页码切换

业务规则也在页面设计阶段一起确定：最多启用六张图片；启用项排在禁用项之前；禁用项不显示启用时间；两种状态都能编辑；移动端每六秒轮播一次。

这一步让我再次意识到，原型只描述页面长什么样，真正决定代码结构的是状态、动作和接口之间的关系。

2. 用页面模型隔离接口字段#

接口使用字符串表示业务枚举：状态 0/1，跳转类型 1/2。模板若直接消费这些值，会出现很多重复判断，所以页面先把接口对象转换成适合展示的 CarouselItem。

1
export interface CarouselItem {
2
  id: string
3
  title: string
4
  jumpType: "link" | "none"
5
  link: string
6
  imageUrl: string
7
  fileId: string
8
  enabled: boolean
9
  enabledAt: string
10
}

转换后，模板只需要判断 record.enabled 和 record.jumpType，不再到处比较魔法字符串：

1
const mapBaseFields = (item: AppBanner) => ({
2
  id: String(item.id),
3
  title: item.title || "",
4
  enabled: item.status === "1",
5
  enabledAt:
6
    item.status === "1" && item.enableTime
7
      ? String(item.enableTime)
8
      : "",
9
  jumpType: item.jumpType === "2" ? "link" : "none",
10
  link: item.jumpUrl || "",
11
})

提交时再做一次反向转换。接口字段的变化被限制在适配函数中，表格和弹窗保持稳定。

3. 新增与编辑共用一个弹窗#

新增、编辑和查看使用同一个 CarouselEditor，通过 mode 区分行为。这样可以复用表单结构、校验规则和图片预览，又不会为三个弹窗复制相同代码。

表单约束包括：

图片名称必填，最多五十个字符；
图片只允许 JPG、PNG，最大 10MB；
跳转类型默认“无跳转”；
选择“跳转”后才展示跳转地址；
跳转地址最多五百个字符，并校验 http/https 协议；
查看模式禁用输入，只保留图片和字段回显。

跳转地址的校验没有只判断是否为空，而是交给 URL 解析：

1
const validateLink = async (_rule: unknown, value: string) => {
2
  if (form.jumpType !== "link") return
3

4
  try {
5
    const url = new URL(value.trim())
6
    if (!["http:", "https:"].includes(url.protocol)) {
7
      throw new Error("Unsupported protocol")
8
    }
9
  } catch {
10
    throw new Error("请输入以 http:// 或 https:// 开头的有效地址")
11
  }
12
}

这里的重点不是校验写得多复杂，而是让表单状态和业务规则一致。用户选了无跳转，页面就不应提交上一次残留的链接。

4. 从 Knife4j 文档整理接口边界#

拿到后端文档后，我先没有急着把 URL 写进页面，而是把轮播配置接口按职责整理了一遍：

方法	路径	用途
`POST`	`/manager/banner`	新增配置
`PUT`	`/manager/banner`	修改配置、切换状态
`GET`	`/manager/banner/{id}`	查询详情
`DELETE`	`/manager/banner/{ids}`	批量删除
`GET`	`/manager/banner/list`	查询全部匹配记录
`GET`	`/manager/banner/page`	分页查询

Knife4j 展示的是网关下的完整服务路径。Portal 的 requestClient 已经配置了 API 基础地址，Vite 代理也会去掉前端代理前缀，所以业务 API 层只保留后端实际控制器路径。

1
import { requestClient } from "#/api/request"
2

3
const ROOT = "/manager/banner"
4

5
export function addAppBanner(data: AppBannerForm) {
6
  return requestClient.post<void>(ROOT, data)
7
}
8

9
export function updateAppBanner(data: AppBannerForm) {
10
  return requestClient.put<void>(ROOT, data)
11
}
12

13
export function getAppBanner(id: number | string) {
14
  return requestClient.get<AppBanner>(`${ROOT}/${id}`)
15
}
16

17
export function removeAppBanners(ids: Array<number | string>) {
18
  return requestClient.delete<void>(`${ROOT}/${ids.join(",")}`)
19
}
20

21
export function getAppBannerPage(params: AppBannerQuery) {
22
  return requestClient.get<AppBannerPage>(`${ROOT}/page`, { params })
23
}

展开收起

API 文件同时声明了 AppBanner、AppBannerForm、AppBannerQuery 和分页响应类型。页面因此能清楚地区分：哪些字段来自列表，哪些字段用于提交，哪些字段只是查询条件。

5. 分页响应为什么没有 `data`#

项目请求拦截器会统一处理 { code, msg, data }。但分页接口返回的是 { code, msg, rows, total }，没有 data 字段。

请求封装已经考虑了这种差异：响应中有 data 时返回 data；没有 data 时，将 rows、total 等剩余字段作为结果返回。因此页面调用分页接口后可以直接读取：

1
const result = await getAppBannerPage({
2
  pageNum: page.value,
3
  pageSize,
4
  title: applied.title || undefined,
5
  status,
6
  orderByColumn: "status",
7
  isAsc: "desc",
8
})
9

10
records.value = result.rows
11
total.value = Number(result.total || 0)

调试接口时，我会先确认三个层次：浏览器实际请求地址、HTTP 状态、业务响应结构。只看控制台中有没有报错，很容易把网关路径和响应适配混在一起。

6. 六张启用上限放在状态动作前#

“最多启用六张”不是列表展示规则，而是状态变更的前置条件。点击启用前，页面先查询当前启用记录：

1
const toggleStatus = async (item: CarouselItem) => {
2
  if (!item.enabled) {
3
    const enabledItems = await getAppBannerList({ status: "1" })
4
    if (enabledItems.length >= MAX_ENABLED_IMAGES) {
5
      message.warning("最多可以启用6张图片")
6
      return
7
    }
8
  }
9

10
  const enabled = !item.enabled
11
  await updateAppBanner(
12
    toBannerForm({
13
      ...item,
14
      enabled,
15
      enabledAt: enabled ? dayjs().format("YYYY-MM-DD HH:mm:ss") : "",
16
    }),
17
  )
18
}

展开收起

页面还用一个 Set 记录正在切换状态的记录 ID，避免用户连续点击同一行。前端检查改善交互，真正的并发上限仍应由后端保证，因为多个管理人员可能同时操作。

7. 图片预览故障：`fileId` 不是 `ossId`#

页面与接口接通后出现了一个很有代表性的问题：列表有图片标题，查看弹窗没有预览，移动端首页也不显示配置图片。

当时两端都使用了下面的写法：

1
const imageUrl = `${apiURL}/resource/oss/preview/${item.fileId}`

从字段名看，这似乎很合理，但直接请求后，资源接口返回“文件数据不存在”。继续查 Knife4j 和项目已有文件代码后，我发现上传与业务保存并不是只有一个 ID。

文件链路实际是：

1
上传图片
2
  ↓ 返回临时附件 ID
3
保存轮播配置并提交 fileIds
4
  ↓ 后端完成业务关联
5
轮播记录中的 fileId 作为附件业务 bizId
6
  ↓ 通过 bizId 查询附件
7
得到真正的 ossId
8
  ↓ 调用资源预览接口

我用现有轮播记录做了逐段验证：

分页接口返回轮播记录和 fileId；
将这个 fileId 直接传给预览接口，返回 JSON 错误；
调用 /manager/fileData/list?bizId={fileId}，可以查到附件记录；
附件记录中的 ossId 与原 fileId 不同；
使用真实 ossId 调用预览接口，响应类型是 image/jpeg。

这次排查最关键的结论是：字段类型都是字符串或长整型，并不代表语义相同。bizId 负责说明文件属于哪个业务，ossId 才是资源服务预览文件时需要的主键。

8. Review：管理端如何恢复图片回显#

管理端将原来的同步映射改成异步映射。先按业务 ID 查询附件，再使用查询结果中的真实 OSS ID 生成预览地址。项目现有的 fileData API 已经会补全 url，页面只消费第一张附件即可。

1
const mapBanner = async (item: AppBanner): Promise<CarouselItem> => {
2
  let imageUrl = ""
3

4
  if (item.fileId !== null && item.fileId !== undefined) {
5
    const files = await fileData({ bizId: item.fileId })
6
    imageUrl = files.rows?.[0]?.url || ""
7
  }
8

9
  return {
10
    id: String(item.id),
11
    title: item.title || "",
12
    fileId: item.fileId ? String(item.fileId) : "",
13
    imageUrl,
14
    enabled: item.status === "1",
15
    enabledAt:
16
      item.status === "1" && item.enableTime
17
        ? String(item.enableTime)
18
        : "",
19
    jumpType: item.jumpType === "2" ? "link" : "none",
20
    link: item.jumpUrl || "",
21
  }
22
}

展开收起

分页一次返回多条记录，所以列表使用 Promise.all 并行补全图片：

1
const result = await getAppBannerPage(query)
2
records.value = await Promise.all((result.rows || []).map(mapBanner))

新增上传后的即时预览仍然使用上传接口刚返回的 ossId。此时附件还没有完成业务关联，它就是资源预览所需的真实 ID：

1
const result = await uploadApi(file)
2
form.fileId = String(result.ossId)
3
form.imageUrl = `${apiURL}/resource/oss/preview/${result.ossId}`

编辑已有记录时还要处理另一个细节：如果用户只改标题或跳转地址，就不应把记录中的业务 fileId 再次作为新附件 ID 提交。现在只有图片发生变化时才发送 fileIds：

1
const imageChanged =
2
  !currentRecord.value || value.fileId !== currentRecord.value.fileId
3

4
const attachmentIds =
5
  imageChanged && value.fileId ? [value.fileId] : undefined
6

7
await updateAppBanner(
8
  toBannerForm({ ...currentRecord.value, ...value }, attachmentIds),
9
)

这样，状态切换和普通字段编辑不会意外改变附件关联，重新上传图片时又能把新的 OSS 文件交给后端绑定。

9. WST 首页的 API 封装#

移动端没有直接复用管理端 API，而是在自己的 src/api/banner.js 中封装首页所需的两个请求。

1
import request from "@/utils/request"
2

3
export function queryEnabledBanners(params = {}) {
4
  return request({
5
    url: "/manager/banner/page",
6
    method: "get",
7
    params: {
8
      pageNum: 1,
9
      pageSize: 6,
10
      status: "1",
11
      orderByColumn: "enableTime",
12
      isAsc: "desc",
13
      ...params,
14
    },
15
  })
16
}
17

18
export function queryBannerFiles(bizId) {
19
  return request({
20
    url: "/manager/fileData/list",
21
    method: "get",
22
    params: { bizId },
23
  })
24
}

展开收起

第一个接口只取启用数据，限制六条并按启用时间倒序；第二个接口完成业务附件 ID 到真实 OSS ID 的转换。页面不再知道完整网关地址，也不重复处理客户端标识、Token 和错误提示。

首页加载时并行补全图片地址：

1
const fetchBannerList = async () => {
2
  const { rows = [] } = await queryEnabledBanners()
3
  const enabledBanners = rows
4
    .filter(item => item.status === "1" && item.fileId)
5
    .slice(0, 6)
6

7
  const resolvedBanners = await Promise.all(
8
    enabledBanners.map(async item => {
9
      const { rows: files = [] } = await queryBannerFiles(item.fileId)
10
      const ossId = files[0]?.ossId
11

12
      return ossId
13
        ? {
14
            ...item,
15
            imageUrl: `${apiURL}/resource/oss/preview/${ossId}`,
16
          }
17
        : null
18
    }),
19
  )
20

21
  bannerList.value = resolvedBanners.filter(Boolean)
22
}

展开收起

模板使用 Vant Swipe，保持原首页 180px 的轮播区域。只有一张时隐藏指示点，多张时每六秒切换：

1
<van-swipe
2
  v-if="bannerList.length"
3
  class="home-banner"
4
  :autoplay="6000"
5
  :show-indicators="bannerList.length > 1"
6
  indicator-color="#ffffff"
7
>
8
  <van-swipe-item v-for="item in bannerList" :key="item.id">
9
    <van-image
10
      width="100%"
11
      height="180"
12
      fit="cover"
13
      :src="item.imageUrl"
14
      :alt="item.title"
15
      @error="handleBannerImageError(item)"
16
      @click="handleBannerClick(item)"
17
    />
18
  </van-swipe-item>
19
</van-swipe>

展开收起

点击行为也严格跟随配置：只有 jumpType === "2" 且地址存在时才跳转。接口为空、请求失败或单张图片失效时，页面保留原首页图片作为兜底，不让首屏出现空白区域。

10. 调试时如何证明链路已经恢复#

这次没有停在“代码看起来正确”。我按真实请求顺序检查了运行结果：

1
轮播分页接口              200 application/json
2
附件关联查询（第一条）    200 application/json
3
附件关联查询（第二条）    200 application/json
4
图片预览（第一张）        200 image/jpeg
5
图片预览（第二张）        200 image/jpeg

然后用移动端尺寸打开首页，等待网络空闲，确认轮播区域显示后端配置的图片。最后分别完成 Portal 与 WST 的构建检查。

这里的验证顺序很重要。若只看到 <img> 没显示就开始改 CSS，很可能越改越远；先看图片请求返回的是图片还是 JSON，往往几分钟就能判断问题属于样式、鉴权、路径还是数据关联。

11. 本次工作的几个记录#

第一，API 文档中的字段名只是入口。遇到文件、用户、组织等关联数据时，还要顺着已有代码和真实响应确认字段语义。

第二，API 层应表达业务动作。页面调用 queryEnabledBanners、queryBannerFiles，比在组件里散落 URL、状态值和分页参数更容易阅读和修改。

第三，上传和业务保存是两个阶段。上传接口返回 OSS ID，保存接口负责把附件和业务关联；查看时再从业务 ID 找回真实文件。忽略中间这一层，就会出现“数据库有配置、对象存储也有文件，但页面永远找不到图片”的情况。

第四，状态更新要控制提交范围。切换启用状态时只提交状态相关字段，图片没有变化就不重新绑定附件。数据越复杂，越不能把整个页面对象不加区分地塞回接口。

这次工作从一个运营位入口开始，最后落到管理端页面、移动端轮播、请求封装和附件模型四条链路。页面实现本身并不算最难，真正有价值的是把一个模糊的“图片不显示”拆成可验证的步骤，并最终找到 bizId 与 ossId 之间那一层容易被忽略的关系。

前端面试提问①

Thu, 10 Sep 2026 00:00:00 GMT

记录了一下前端面试的提问，整合了一下每道题。记录了些自己目前的理解。

一、Vue 3 核心知识#

1. Vue 3 的响应式是怎样工作的？#

我会沿着“读取数据、建立依赖、修改数据、通知更新”这条线来解释。对响应式对象，Vue 3 使用 Proxy 拦截属性访问和修改。响应式副作用执行期间读取属性会建立依赖关系，相关属性发生变化时再通知依赖更新。这里我还会补充一句：组件更新经过调度与批处理，不是每次赋值都立即操作 DOM。

追问：ref 也是把基本类型交给 Proxy 吗？

复习到这里，我会把 ref 和 reactive 分开记。ref 通过 .value 的 getter/setter 收集与触发依赖；普通 ref 接收对象时，会把对象转换为深层响应式对象。reactive 面向对象、数组和受支持的集合类型，不能直接接收数字或字符串作为响应式目标。这也是我对照 Vue 响应式原理时重点确认的区别。

1
import { ref, reactive, nextTick } from 'vue'
2

3
const count = ref(0)
4
const form = reactive({ name: '', address: '' })
5

6
async function increment() {
7
  count.value += 1
8
  await nextTick()
9
  // 此时再读取依赖本次状态变化的 DOM
10
}

追问：Vue 2 与 Vue 3 有什么差异？

Vue 2 对对象属性使用 Object.defineProperty，新增、删除属性以及直接修改数组索引或 length 存在检测限制，通常需要 Vue.set、Vue.delete 或 splice 等方式。Vue 3 的 Proxy 改善了这些限制，但仍应通过代理对象修改数据；直接修改原始对象不会触发代理拦截。

2. setup 的作用是什么？#

我理解 setup 的价值，主要在于能按业务功能组织代码。例如一个查询功能的状态、计算属性、监听和生命周期逻辑可以放在一起，阅读时更容易顺着业务走。setup 是组合式 API 的入口，早于选项式 beforeCreate 执行，不能通过 this 访问组件实例。复习时我也会注意，组合式与选项式 API 可以共存。

普通 setup 接收 props 和 context，context 提供 attrs、slots、emit、expose 等能力。<script setup> 是编译语法糖，顶层绑定可直接用于模板。defineProps、defineEmits 是编译宏，不需要导入；ref、computed 等运行时 API 仍需导入，除非项目配置了自动导入插件。参见 script setup 文档。

追问：解构 props 一定会丢失响应式吗？

普通 JavaScript 解构基本类型属性会取得当时的值，可使用 toRef、toRefs 或 getter 保留读取关系。但 Vue 3.5 及以上对同一 <script setup> 内从 defineProps 解构的变量提供了编译支持。传入 watch 或外部函数时仍要留意是否传递了 getter，不能忽略版本和使用位置。参见响应式 Props 解构。

3. computed、watch 和 watchEffect 如何选择？#

我通常先判断自己是在“计算一个值”，还是“执行一件事”。订单金额汇总、按钮是否可操作这类派生值，我会用 computed；状态变化后需要请求接口、写缓存，我会用 watch；依赖简单且适合自动收集时，再考虑 watchEffect。

computed 的 getter 应尽量保持纯计算。watch 的深度监听可能增加遍历成本，监听明确字段通常更容易维护。异步监听还要处理旧请求晚返回的问题，不能只讨论“数据是否变了”。

二、CSS 选择器与层叠#

4. 常用选择器有哪些？#

我把常用选择器按匹配方式列在一起。复习时会结合页面结构看它们选中了谁，而不只是记住符号的名字。

类型	示例	含义
基础	`*`、`div`、`.card`、`#app`	通配、标签、类、ID
属性	`[type="text"]`、`[class*="box"]`	匹配属性或属性值
后代、子代	`.card p`、`.card > p`	所有后代、直接子元素
兄弟	`h2 + p`、`h2 ~ p`	紧邻的后续兄弟、所有匹配的后续兄弟
伪类	`:hover`、`:focus`、`:nth-child(2)`、`:not(.disabled)`	状态或结构条件
伪元素	`::before`、`::after`、`::first-letter`	指定元素的某个部分

追问：nth-child 和 nth-of-type 有什么区别？

前者按兄弟元素中的位置匹配，后者按同类型兄弟元素中的位置匹配。容器中混有多种标签时，结果可能不同。

5. 为什么不能只背“important 大于 ID 大于 class”？#

我现在会先解释层叠条件，再比较选择器。浏览器先考虑来源、重要性和层叠层等因素，再在可比较的声明之间比较选择器优先级。!important 是声明的重要性标记，不是选择器权重。

在相同可比较条件下，优先级按 ID、类/属性/伪类、类型/伪元素三组比较；通配符和组合符不增加权重。:where() 的优先级为零，:is()、:not()、:has() 的参数会影响其优先级。权重相同还要继续考虑作用域邻近性、声明顺序等因素。参见 MDN：选择器优先级。

追问：组件库样式覆盖不生效怎么办？

遇到这种情况，我会先在开发者工具中查看实际命中的规则、加载顺序、scoped 属性和 Teleport 后的 DOM 位置，再选择组件属性、主题变量或局部深度选择器处理。先看清规则为什么没生效，才知道应该改哪里。

三、页面加载与性能#

6. 用户说页面很慢，你先做什么？#

我会先确认慢在首次访问、切换页面、接口返回还是交互响应，再决定从哪里查。用 Network 看资源体积、缓存和请求瀑布，用 Performance 看主线程长任务和渲染，再结合 LCP、INP、CLS 判断体验问题。我把排查线索和对应措施整理成了下面这张表。

问题证据	优化方向	验证重点
首屏图片过大	合理尺寸、WebP/AVIF、CDN	图片传输量和 LCP
初始 JS 太大	路由/组件拆分、按需加载、移除无用依赖	下载、解析与执行耗时
相同资源反复下载	检查 Cache-Control、ETag	缓存命中与重复传输
列表节点过多	分页或虚拟列表	节点数、滚动和交互耗时
DOM 读写交错	集中读写、避免重复布局计算	布局次数和长任务
字体拖慢显示	子集化、合理回退字体	字体体积、文字显示与偏移

Gzip/Brotli 适合压缩文本资源。首屏关键图片通常不应懒加载；非首屏图片才适合延迟加载。骨架屏改善等待感受，但不会直接缩短接口耗时。

7. defer、async 和预加载怎么用？#

我会先看脚本之间有没有执行顺序要求。对普通外部脚本，defer 允许并行下载，在文档解析完成后按顺序执行；async 下载完成后尽快执行，不保证脚本间顺序，适合独立脚本。模块脚本默认具有类似 defer 的行为。

preload 用于当前页面明确需要的关键资源；prefetch 面向后续可能用到的资源；preconnect 提前建立到目标来源的连接。预加载过多会争抢带宽，应以实际请求链路为依据。

追问：HTTP/2、SSR 能解决所有慢页面吗？

不能。HTTP/2 多路复用减少应用层串行等待，但 TCP 丢包仍可能影响同一连接上的流。SSR 按请求生成 HTML，SSG 通常在构建时生成 HTML；二者都要权衡数据时效、生成成本和客户端交互脚本。现代协议下也不应为了减少请求数，把所有代码合成一个巨型文件。

四、技术选型如何回答#

8. 面试官问“你了解哪些新技术”，怎样避免堆名词？#

我会从项目里的 Vue、Vite、uni-app 和 Astro 讲起，再补充正在了解的技术。实际用过的部分，我会结合代码解释；还停留在学习阶段的部分，就说明它解决什么问题、有哪些限制。下面这张表是我给自己整理的复习提纲。

技术方向	可以讨论的价值	需要交代的边界
Vue 组合式 API、Teleport	逻辑复用、弹层挂载	状态归属、DOM 位置与样式
React Transitions、Suspense	更新优先级与异步 UI 边界	依赖版本和框架集成，不能泛化为任意请求自动挂起
Svelte、Solid	编译优化或细粒度更新	避免无实测依据的性能排名
Vite、Rspack、Turbopack	开发反馈与构建效率	确认具体版本、插件和配置兼容性
WebAssembly	部分计算密集任务	数据传递成本，不能直接替代所有页面逻辑
容器查询、`:has()`	基于容器尺寸或关系选择布局	目标运行环境是否支持
TanStack Query	服务端状态缓存与重新获取	不等于自动解决所有防抖、鉴权与业务状态问题
uni-app / uni-app x	跨端开发	产品路线和渲染机制不能混为一谈

整理构建工具这部分时，我也会回头看项目的版本。例如我的管理端声明 Vite 6.4.1，讨论实现细节时就应结合这一版本，后续升级再重新确认。

五、HTTP 状态码#

9. 高频状态码怎么区分？#

我按成功、重定向、客户端错误和服务端错误来记，再把容易混淆的状态码放在一起比较。

状态码	含义
200 / 201 / 204	成功 / 创建成功 / 成功且无响应正文
301 / 302	永久 / 临时重定向
304	条件请求确认资源未修改，可复用缓存
400 / 401 / 403	请求有问题 / 需要认证 / 拒绝访问
404 / 405	资源未找到 / 方法不被允许
429	请求过于频繁
500	服务端遇到未预期情况
502	网关收到无效上游响应
503	服务暂时无法处理请求
504	网关等待上游响应超时

这些是 HTTP 层语义，不能仅凭 502 断言后端一定宕机。参见 MDN：HTTP 响应状态码。

追问：接口返回 200，就代表业务成功吗？

我会结合管理端的请求封装回答这道题：HTTP 状态与响应体里的业务 code 是两个层次。项目里还会读取 res.data.code，所以排查时，我会一起看 HTTP status、业务 code、响应内容和请求链路。

六、上传报错实战#

10. Axios ERR_NETWORK、ERR_CONNECTION_RESET 怎么排查？#

看到这类报错，我会先分清浏览器给出的现象。ERR_NETWORK 表示未获得可正常交付给 JavaScript 的响应，可能涉及 CORS、连接异常或其他浏览器网络限制；ERR_CONNECTION_RESET 表示连接被重置。仅凭这两个字符串，我还不能确定是哪台服务或哪段配置导致。

我参考的资料没有展开后续排查过程，因此这里补上自己的排查顺序。真遇到上传失败时，我会逐项收集证据，再判断原因。

检查 Network 中请求 URL、方法、预检请求、响应头和失败时间，确认开发代理前缀是否正确。
对比小文件、大文件与普通接口，观察是否存在体积或持续时间阈值。
检查代理的请求体限制、超时、上游连接和后端 multipart 配置，并对照同一时刻的日志。
检查上传参数：字段名、FormData、鉴权头是否正确。浏览器发送 FormData 时通常让浏览器生成带 boundary 的 Content-Type。
分别验证直连后端和经过代理的路径。直连成功只能缩小问题范围，还需要比较路径、协议和请求头。

追问：把 Axios timeout 调大就可以了吗？

我会先确认失败是否真的来自客户端超时。只有超时确实过短时，调大 timeout 才可能有效；它不能修复文件体积限制、CORS、代理主动断开或服务异常。对于上传，我也会把前端提示与服务端校验分开考虑：文件类型、大小和资源归属仍需在服务端独立检查。

七、面试前快速复述#

最后，我把这轮复习压缩成七条提醒，方便面试前再过一遍：

响应式：对象代理与 ref 的 value 访问器要区分，更新有批处理。
setup：按功能组织逻辑，分清编译宏、运行时 API 和自动导入。
CSS：先看层叠条件，再比较权重，结合实际 DOM 排查。
性能：先定位瓶颈，再提出措施，用相同条件的指标验证。
技术选型：解释收益、成本与版本边界，坦诚说明实践范围。
HTTP：区分传输状态、业务状态和没有正常响应的网络错误。
上传：沿浏览器、代理、后端逐层取证，不凭一条报错锁定原因。

前端项目面试提问①：从技术栈到业务实现

Thu, 10 Sep 2026 00:00:00 GMT

整理完基础题以后，我又把手头的几个项目翻了一遍。Vue、Pinia、Axios 这些名字并不难记，真正需要准备的是：如果面试官继续问为什么这样写、换一种场景会不会出问题，我能不能顺着代码解释下去。

这篇就从无人机配送管理端开始，再聊凭证报表、小程序和自己的博客。我把项目里现有的处理方式与自己的理解放在一起，遇到还不完善的地方，也记下接下来会怎样改进。

一、先把项目技术栈讲清楚#

项目	使用的技术与实现	我重点复盘的问题
无人机配送管理端	Vue 3.5.26、Vite 6.4.1、Element Plus、Pinia、Vue Router、Axios、ECharts	权限、订单流程、请求封装、可视化
无人机配送小程序	uni-app、Vue 3、Pinia、微信小程序运行环境	登录、请求并发、平台适配、地图
凭证查询管理端	Vue 3、Element Plus、Pinia、Axios、共享报表查询 composable	单位/年度上下文、竞态、报表复用
健身小程序	uni-app、Vue 3、TypeScript、Pinia、Vitest	类型建模、本地与云端数据合并
个人博客	Astro 7.0.7、Svelte 5、TypeScript、Tailwind CSS 4、Pagefind	内容集合、交互边界、静态搜索

我先按当前 package.json 整理了这张表。涉及精确版本时，还需要结合锁文件确认范围依赖最终安装的版本。介绍项目时，我也会分别说明哪些地方使用 JavaScript、哪些地方使用 TypeScript，以及普通 uni-app 与 uni-app x 的区别。

二、无人机配送管理端#

1. 为什么选择 Vue 3 + Element Plus + Pinia？#

我会先从管理端每天处理的事情讲起：查列表、筛选订单、填写表单、打开弹窗，再根据权限进入不同页面。Element Plus 提供了这些常用组件，Vue 组合式 API 便于组织查询与编辑逻辑，Pinia 则承载用户、权限、设置等跨页面状态。

这个项目是在若依体系上继续开发的，所以我理解技术选择时，也会把已有代码和维护成本考虑进去。

追问：所有变量都放 Pinia 吗？

我会按状态的使用范围来分。弹窗开关、当前表单和局部 loading 通常留在组件内；多个页面共享且生命周期更长的数据才放 store。对于服务端数据，我还会单独考虑是否缓存、何时失效。

2. 动态路由是怎样加载的？隐藏按钮能保证安全吗？#

我会从 uav-ui/src/permission.js 的导航守卫讲起：先检查 token，当角色尚未加载时获取用户信息，生成可访问路由，通过 router.addRoute 注册，再重新导航到目标地址。沿着这条链路，还能看到登录白名单和锁屏路由的处理。

这里我会把页面权限和接口权限分开解释。动态路由控制可达页面，按钮权限控制操作入口；后端必须独立校验操作权限和资源归属。用户可以绕过页面直接请求接口，所以只隐藏按钮还不够。

追问：刷新页面后为什么要重新导航？

因为刷新后内存中的动态路由需要重新注册。注册完成再匹配目标地址，才能进入正确页面；同时要保证初始化条件收敛，避免反复加载形成重定向循环。退出或切换账号后的路由清理，也是需要单独检查的边界。

3. Axios 封装具体做了什么？#

复盘 uav-ui/src/utils/request.js 时，我按一次请求的过程来梳理：设置基础地址和 10 秒超时，注入 Bearer token，处理 GET 参数，再处理短时间重复提交、业务错误提示和二进制下载。登录失效时，还有 isRelogin.show 避免重复弹出提示。

我理解这几层的分工是：通用请求层负责传输和公共错误处理，业务 API 层表达订单、异常等业务动作，页面负责 loading、交互反馈和结果更新。排查错误时，我会分别看 HTTP 状态与响应体中的 code。

追问：这个封装还可以改进什么？

接下来如果继续完善这层封装，我会检查请求拦截器的失败分支是否正确返回拒绝态，以及业务 code 使用 || 200 是否会掩盖合法的零值。动手前，我会先确认接口约定，再决定具体改法。

4. 前端防重复提交等于接口幂等吗？#

我在请求层看到的处理，是对 POST/PUT 按 URL、数据和时间间隔判断重复，默认间隔为 1 秒，并只保存最近一次请求记录；较大的请求会跳过这项前端判断。

所以我会把它解释为减少误点的一道措施。多标签页、多设备、刷新或绕过前端的请求，仍可能重复到达服务端。对于创建订单、退款等操作，我还会考虑服务端的业务唯一约束、幂等键或条件状态更新。

追问：按钮禁用后还需要后端校验状态吗？

需要。用户打开页面之后，另一位操作员可能已经处理了订单。前端展示的是一个时间点的状态；真正提交时必须重新判断当前状态是否允许该动作。

5. 订单按钮、状态标签和操作流程如何保持一致？#

结合前面整理过的订单列表，我会先统一状态含义和允许动作，让标签负责展示，按钮依据“状态允许 + 用户有权限”决定入口。如果接口拒绝了状态过期的操作，我会提示用户并刷新详情，让页面重新对齐服务端状态。

验证这部分时，我会沿业务路径考虑：待审核订单被另一人先处理、退款后重复点击、旧页面提交失效动作。这样才能检查按钮背后的流程是否一致。

6. 地图和 ECharts 页面如何避免越用越卡？#

如果要继续优化这类页面，我会先检查实例的创建和销毁：将地图或图表实例与业务数据分开管理，尽量复用实例更新数据；离开页面时解除监听、停止轮询并释放实例。对于高频位置更新，我会根据展示需求节流，并限制轨迹数据的累积范围。

追问：地图偏移和接口慢是同一种问题吗？

我会把这两个问题分开排查。地图偏移时先核对经纬度顺序、坐标系、时间戳和有效范围。配送小程序轨迹页调用定位时请求 gcj02，其他来源坐标仍需确认；对于实时数据，我还会检查是否存在乱序和过期点。

三、凭证查询与财务报表#

7. 用户快速切换单位和月份，旧请求覆盖新结果怎么办？#

这道题我会结合报表查询来讲。ruoyi-ui/src/views/report/composables/useFinancialReportQuery.js 使用递增的 requestSerial，每次请求保存当时序号，返回后只有仍匹配最新序号才更新 rows；catch 与 finally 也检查序号。

我理解这里最关键的一点，是请求返回顺序不一定等于发起顺序。比较序号不仅能挡住旧数据，也能避免旧错误提示和旧请求的 loading 清理影响当前查询。切换单位、年度或月份时，代码会让旧序号失效并重置行数据。我把核心过程简化成下面的例子：

1
// 简化示意：对应项目中的序号思路
2
let serial = 0
3

4
async function load(query) {
5
  const current = ++serial
6
  loading.value = true
7
  try {
8
    const result = await fetchRows(query)
9
    if (current === serial) rows.value = result
10
  } catch (error) {
11
    if (current === serial) showError(error)
12
  } finally {
13
    if (current === serial) loading.value = false
14
  }
15
}

展开收起

追问：序号机制会取消网络请求吗？

不会，它只控制结果是否生效。取消请求可以减少客户端等待和资源占用，但请求可能已经到达服务端，仍应保留结果时序保护。验证时可让第一次请求延迟、第二次先返回，确认旧数据和旧错误都不会污染新查询。

8. 为什么把报表查询抽成 composable？#

回头看这个共享函数，我觉得比较清楚的地方是它把共同流程和报表差异分开了。函数接收 request、createEmptyRows、mapRows 和 errorMessage，集中处理单位/年度上下文、月份、loading、竞态和失败重置，各报表提供自己的数据转换。

如果面试官问我抽象的边界，我会回答：复用查询流程，保留各报表自己的列结构与金额映射。这样既减少重复逻辑，也不用让一个组件承担所有报表差异。

追问：缓存报表时 key 怎么设计？

如果后续增加报表缓存，我会让 key 至少包含单位、年度、月份和报表类型，并考虑用户身份或权限变化造成的隔离需求。只用月份做 key 会把不同单位的结果混在一起；退出登录时，我也需要处理敏感缓存。

四、无人机配送小程序#

9. uni-app 为什么还需要微信适配层？#

结合小程序的登录和授权流程，我理解 uni-app 统一的是部分开发写法，微信登录、手机号授权、订阅消息、隐私授权等能力仍受平台 API 和调用时机约束。把平台能力封装起来以后，我在页面里就能更集中地处理业务结果，把平台检测、错误转换和回调适配放到底层。

追问：H5 正常就说明小程序正常吗？

我不会只用 H5 的结果判断小程序。两者的运行环境、组件能力、网络配置与权限交互不同，我需要在目标小程序环境验证；涉及授权和设备能力的路径，还要真机确认。

10. 多个请求同时 loading，怎么避免一个请求先结束就把提示关掉？#

这部分我会拿 uav-mmp/utils/request.js 中的 loadingCount 举例：用计数记录正在展示加载提示的请求数量，第一次开始时显示，计数归零时隐藏。

我理解计数器的好处，是能表达多个请求同时进行的状态。检查这段逻辑时，我会特别留意成功、失败和取消路径是否成对清理；如果只在成功回调里减计数，遮罩就可能残留。

追问：取消旧请求与防重复提交一样吗？

不一样。该请求工具还有 pendingTasks 和取消旧任务的辅助逻辑；取消是控制请求生命周期，防重是减少相同提交，幂等是重复业务动作产生一致结果。三者要分别设计，不能互相替代。

11. 小程序上传图片成功后，为什么不能只保存临时路径？#

我会把“选到图片”和“保存业务凭证”看成两个阶段。临时路径用于当前设备上的文件访问，不能当成长期业务凭证。设计这条链路时，我会在上传完成后保存服务端返回的文件标识，再由订单接口关联；预览则按资源访问方式获取内容，避免把长期 token 拼进公开 URL。

追问：上传成功但订单提交失败呢？

这种情况下，我会继续考虑未关联文件的清理和重试策略。重新提交时，可以复用仍有效的已上传文件标识，同时由后端检查所有权，避免把其他用户的文件关联到当前订单。

五、健身小程序#

12. TypeScript 给这个项目带来了什么？#

我会从项目里的 src/types/domain.ts 讲起，再看数据合并函数使用的 WorkoutSession 和 CheckIn 类型。工程中还配置了 vue-tsc 与 Vitest，分别用于类型检查和测试。

对我来说，类型最直接的帮助是明确训练记录、打卡数据和函数输入输出，重构时更容易发现字段不一致。不过面对云端响应和本地旧缓存，我仍需要运行时解析、校验和必要的数据迁移，不能只依靠类型声明。

13. 本地训练记录和云端记录怎样合并？#

我会按“用什么识别同一条记录、冲突时保留哪条”来解释 src/utils/cloud-merge.ts。当前函数使用 Map 按 session.id 去重，以 completedAt 或 startedAt 比较时间，保留较新的记录并倒序排列。同一天的打卡按 date 合并，sessionIds 用 Set 去重。

追问：时间相同、用户删除记录或设备时间错误怎么办？

当前函数按本地数组、远端数组的顺序遍历，时间相等时后来的记录会覆盖先前记录。因此同 ID 同时间的远端记录会胜出。函数本身没有表达删除墓碑，也没有解决设备时钟偏差。

这也是我后续会继续完善的地方：根据同步协议引入版本号、服务端更新时间和删除标记，把冲突处理约定清楚。当前按时间覆盖的规则解决了一部分合并问题，删除和时钟偏差还需要另外设计。

追问：你会测什么？

我会优先补充同 ID 新旧记录、同时间冲突、空数组、同日期多个 sessionId，以及异常日期输入这些用例。介绍测试情况时，我会以实际编写和运行的结果为准，明确哪些规则已验证、哪些还需要补充。

六、博客与内容工程#

14. 为什么博客使用 Astro，而管理端使用 Vue？#

我对这两个项目的需求判断不同。自己的博客主要交付文章内容，管理端则有大量连续交互和业务状态。Astro 适合以页面内容为中心组织站点，并按需要给交互组件加载客户端能力；Vue 管理端便于维护复杂表单、路由和状态流。

我的博客使用 Astro 内容集合读取 Markdown/MDX，通过 schema 约束标题、发布日期、封面、标签等字段，也集成了 Svelte。分析客户端开销时，我还会继续看具体组件的使用方式，确认哪些交互需要发送客户端脚本。

15. 新增文章为什么不用手动改文章列表？#

我平时新增文章的入口就是 src/content/posts。src/content.config.ts 的 glob loader 会扫描这里的 Markdown/MDX 文件，所以按既有 frontmatter 格式写好文章，就能进入内容集合。

追问：Pagefind 的搜索数据什么时候更新？

我在 build 脚本里可以看到，站点生成后还会执行 pagefind --site dist。因此写完文章源文件后，我还需要通过后续构建和部署，让线上页面与搜索索引一起更新。

16. 如果面试官要求你证明优化有效，怎么回答？#

我会提供同一设备、网络、数据规模与操作路径下的对比，并说明测量工具和指标。请求竞态可以用可控延迟复现；首屏优化可以对比资源体积与 LCP；同步合并可以用固定输入验证规则。如果某项优化还没有测量，我会先说明目前的判断依据，再补上验证计划。

七、一段可复述的项目介绍#

我接触的前端项目覆盖管理端、小程序和内容站点。管理端使用 Vue 3、Element Plus、Pinia 和 Axios，重点处理权限、业务状态和查询交互；凭证报表中通过共享 composable 与请求序号处理重复逻辑和异步竞态；小程序需要处理平台能力和并发请求；健身项目还涉及类型建模与本地、云端记录合并；博客则通过 Astro 内容集合组织文章。介绍具体贡献时，我会进一步说明自己实际负责的模块、遇到的问题和验证证据。

整理到这里，我给自己留下的复习方式，就是选一条真实链路从头讲到尾：用户做了什么、状态如何变化、请求如何到达后端、失败如何恢复。讲不顺的地方，再回到代码里看一遍；还没有处理好的边界，就记到后续改进里。

小程序开发日记⑨：微信开放接口与原生组件调用

Sun, 23 Aug 2026 00:00:00 GMT

这个项目虽然使用 uni-app 和 Vue 3 开发，但登录、手机号、订阅消息、地图、媒体和客服等能力最终仍来自微信小程序运行环境。框架解决跨端写法，开放能力的授权时机、事件结构和平台限制却不能被忽略。

本篇不打算做一份微信 API 百科，而是沿着项目里的真实使用场景，记录哪些能力通过函数调用、哪些必须依赖原生组件，以及封装时踩过的几个关键坑。

1. 项目中使用的微信能力#

能力	API 或组件	项目场景
微信登录	`wx.login`、`wx.checkSession`	建立和恢复登录态
手机号授权	`button open-type="getPhoneNumber"`	手机号快捷登录
隐私授权	`wx.getPrivacySetting`、`wx.requirePrivacyAuthorize`	登录前隐私合规确认
订阅消息	`wx.requestSubscribeMessage`	订单完成和状态提醒
头像昵称	`chooseAvatar`、`type="nickname"`	维护个人资料
图片选择	`wx.chooseMedia`	订单凭证和异常证据
文件上传	`uni.uploadFile`	上传图片到业务服务器
定位地图	`uni.getLocation`、`wx.createMapContext`、`map`	服务范围、选点和轨迹
图片预览	`uni.previewImage`	查看凭证和签收图
客服	`button open-type="contact"`	订单与异常咨询
分享	`wx.showShareMenu`、`onShareAppMessage`	分享订单信息
剪贴板	`uni.getClipboardData`、`setClipboardData`	粘贴、复制订单号

2. 为什么建立 `utils/wx` 适配层#

项目没有在每个页面直接编写大量 wx.xxx 回调，而是把平台能力集中在 utils/wx 下：

1
utils/wx
2
 ├─ login.js          微信登录与会话检查
3
 ├─ phone.js          手机号授权事件解析
4
 ├─ privacy.js        隐私授权
5
 ├─ subscribeMsg.js   订阅消息
6
 ├─ media.js          图片选择与上传
7
 ├─ map.js            定位与地图上下文
8
 ├─ share.js          分享菜单
9
 ├─ clipboard.js      剪贴板
10
 └─ authImage.js      鉴权图片下载和本地缓存

封装后的页面可以使用 Promise 和 async/await，平台错误也能统一转换成面向用户的消息。

1
export function login() {
2
  return new Promise((resolve, reject) => {
3
    wx.login({
4
      success: result => result.code
5
        ? resolve(result.code)
6
        : reject(new Error('微信登录未获取到 code')),
7
      fail: error => reject(new Error(error?.errMsg || '微信登录失败'))
8
    })
9
  })
10
}

适配层不是为了把 wx 三个字藏起来，而是隔离回调、错误格式和运行环境差异。

3. `wx.login` 与会话恢复#

登录流程首先检查本地 token。若微信会话仍有效，则使用原 token 获取最新用户资料；会话失效或资料接口拒绝后，再重新调用 wx.login 获取一次性 code。

1
if (existingToken && await checkSession()) {
2
  const response = await UserApi.getProfile()
3
  return { token: existingToken, userInfo: response.data }
4
}
5

6
const code = await wxLogin()
7
const response = await UserApi.login({ code })

微信 code 只能使用一次，因此 wxLoginFlow 使用共享 Promise 防止多个页面同时发起登录：

1
let loginFlowPromise = null
2

3
export async function wxLoginFlow(options = {}) {
4
  if (loginFlowPromise) return loginFlowPromise
5
  loginFlowPromise = runLoginFlow(options)
6
  try {
7
    return await loginFlowPromise
8
  } finally {
9
    loginFlowPromise = null
10
  }
11
}

这比每个请求发现未登录后各自调用 wx.login 稳定得多。

4. 手机号能力必须由原生按钮触发#

手机号授权不是普通函数调用，需要使用微信原生按钮：

1
<button
2
  open-type="getPhoneNumber"
3
  @click="preparePrivacy"
4
  @getphonenumber="onGetPhoneNumber"
5
>
6
  允许并登录
7
</button>

授权结果在事件的 detail.code 中。工具函数只解析 code，并区分拒绝与异常：

1
export function getPhoneCodeFromEvent(event) {
2
  if (event?.detail?.code) return event.detail.code
3
  const message = String(event?.detail?.errMsg || '')
4
  if (message.includes('deny') || message.includes('cancel')) {
5
    throw new Error('您已拒绝手机号授权')
6
  }
7
  throw new Error('未获取到手机号授权凭证')
8
}

随后同时提交 wx.login code 与 phoneCode，由后端向微信服务换取身份和手机号。phoneCode 不是手机号本身，前端不解析敏感数据。

5. 隐私授权与用户手势#

登录弹窗在用户点击允许按钮时预先调用 ensurePrivacyAuthorized，手机号事件返回后等待同一个 Promise：

1
const preparePrivacy = () => {
2
  privacyPromise = ensurePrivacyAuthorized()
3
}
4

5
const onGetPhoneNumber = async event => {
6
  const phoneCode = getPhoneCodeFromEvent(event)
7
  await (privacyPromise || ensurePrivacyAuthorized())
8
  await auth.phoneLogin({ phoneCode })
9
}

隐私相关 API 先判断运行环境是否支持。旧基础库缺少方法时安全放行，支持时按微信流程请求授权。

这里的关键是授权动作要紧邻用户手势。不能在页面加载后无理由弹出手机号、订阅消息或隐私授权。

6. 订阅消息调用时机#

订单支付前，页面同步创建订阅请求，再继续支付流程：

1
const subscribeRequest = requestSubscribeMessage([
2
  ORDER_STATUS_TEMPLATE_ID
3
])
4

5
await OrderApi.payOrder(orderId)
6
await requestOrderCompletionSubscribe(subscribeRequest)

wx.requestSubscribeMessage 对调用时机较敏感，封装中在 Promise 构造阶段立即执行原生 API，调用前不能先插入无关的 await。

授权结果不是简单的布尔值，而是以模板 ID 为键：

1
const accepted = result?.[ORDER_STATUS_TEMPLATE_ID] === 'accept'

用户接受后，前端向业务后端上报订阅次数。上报失败只记录警告，不阻断支付，因为订阅提醒是附加能力，不能反过来让核心交易失败。

7. `chooseAvatar` 与昵称输入#

个人中心使用原生头像选择按钮：

1
<button open-type="chooseAvatar" @chooseavatar="onChooseAvatar">
2
  <image :src="auth.avatarDisplayUrl" />
3
</button>

事件返回本地临时文件路径，页面调用头像上传接口，成功后重新获取鉴权图片。

昵称使用：

1
<input type="nickname" name="nickname" maxlength="30" />

即使使用微信昵称能力，提交前仍要做空值、长度与内容校验，最终资料以业务后端保存结果为准。

8. 图片选择、上传与预览#

订单和异常反馈通过 wx.chooseMedia 选择相册或相机图片：

1
wx.chooseMedia({
2
  count,
3
  mediaType: ['image'],
4
  sourceType: ['album', 'camera'],
5
  sizeType: ['compressed'],
6
  camera: 'back'
7
})

返回的 tempFilePath 是临时本地路径。在开发者工具中它可能表现为 http://tmp/...，仍应作为本地文件交给 uni.uploadFile，不能因为长得像 URL 就跳过。

上传方法手动加入 Authorization，并解析字符串形式的响应体：

1
uni.uploadFile({
2
  url: apiUrl,
3
  filePath,
4
  name: 'file',
5
  formData,
6
  header: { Authorization: `Bearer ${token}` }
7
})

订单详情使用 uni.previewImage 打开凭证大图。预览数组使用已经下载好的本地鉴权图片路径，避免原始受保护 URL 无法携带 token。

9. 鉴权图片与文件系统#

头像和订单凭证并非公开静态资源。项目使用 uni.request 以 arraybuffer 获取图片，再通过 wx.getFileSystemManager 写入 USER_DATA_PATH：

1
fileSystem.writeFile({
2
  filePath: `${wx.env.USER_DATA_PATH}/auth-image-${key}.jpg`,
3
  data: response.data,
4
  success: () => resolve(filePath)
5
})

返回的本地路径才能稳定交给 <image>。缓存强制刷新时删除旧文件；退出登录时清空全部鉴权图片，防止不同账号之间复用缓存。

响应还必须检查 Content-Type。有些业务错误使用 HTTP 200 返回 JSON，如果不识别，错误 JSON 会被当成 jpg 写进文件系统，最后页面只会留下一个让人摸不着头脑的破图标。

10. 地图组件和定位接口#

服务范围、位置选择和订单轨迹都使用原生 <map>：

1
<map
2
  id="tracking-map"
3
  :latitude="latitude"
4
  :longitude="longitude"
5
  :markers="markers"
6
  :polyline="polylines"
7
  :scale="mapScale"
8
  show-location
9
/>

页面通过 wx.createMapContext 获取上下文，执行 includePoints、moveToLocation 等命令：

1
const mapContext = wx.createMapContext('tracking-map')
2
mapContext.includePoints({ points, padding: [72, 48, 180, 48] })

用户定位调用 uni.getLocation({ type: 'gcj02' })。权限被拒绝时可以使用 uni.getSetting 检查状态，并由用户主动打开 uni.openSetting；页面仍保留搜索和拖图选点作为降级入口。

marker、polyline 和 circle 应使用 map 原生属性。把普通 <image> 绝对定位在地图上表示无人机，会在地图缩放后与航线发生偏移。

11. 微信客服组件#

首页、订单列表、订单详情和轨迹页都使用：

1
<button open-type="contact">在线客服</button>

客服同样依赖原生 button，普通点击方法不能完整替代。业务页面只需决定何时展示入口，具体会话由微信客服能力承接。

在订单详情中，客服入口与支付、取消等业务按钮分开。客服联系不上不应影响订单状态操作，订单接口失败也不应让客服按钮消失。

12. 分享能力#

订单详情使用 uni-app 生命周期定义分享内容：

1
onShareAppMessage(() => ({
2
  title: `订单 ${detail.value.orderNo}`,
3
  path: `/pages/order/detail?orderId=${orderId.value}`
4
}))

工具层通过 wx.showShareMenu 和 wx.updateShareMenu 开启好友与朋友圈分享。分享路径携带业务参数，但详情页仍需重新校验登录和订单权限，不能因为别人拿到了链接就直接展示受保护数据。

13. 剪贴板能力#

快递单号和外卖订单号支持从剪贴板粘贴，详情中的订单号也可以复制：

1
const value = await readText()
2
order.courierNo = String(value).trim()
3

4
await copyText(detail.value.orderNo)

读取剪贴板后仍执行格式和长度校验，不能把整段聊天记录原样提交。剪贴板只是输入捷径，不是可信数据源。

14. 调用微信能力时总结出的规则#

14.1 区分函数 API 和组件开放能力#

wx.login、chooseMedia 可以封装成函数；getPhoneNumber、chooseAvatar、contact 必须由带 open-type 的原生按钮触发。试图把后一类完全搬进普通 JavaScript 方法，往往会失去微信所需的用户手势上下文。

14.2 授权失败不等于业务失败#

用户拒绝定位后仍可手动选点，拒绝订阅后仍可支付，客服不可用也不影响查看订单。只有手机号登录这种业务身份前提，才会阻止进入受保护页面。

14.3 平台返回值必须再做业务适配#

微信返回 code、临时路径、授权字典和地图上下文；页面真正需要的是 token、凭证记录、是否订阅和业务坐标。适配层负责把平台结果转换成项目语言。

14.4 注意生命周期与一次性凭证#

15. 本篇小结#

在 uni-app 里写微信小程序，最容易产生的错觉是“只要都写成 Promise，它们就是普通接口了”。实际上，授权能力依然受用户手势、原生组件、基础库版本和隐私规则约束。

把微信能力集中封装以后，页面代码确实清爽了很多；但每次看到 open-type，我还是会提醒自己：这不是一个普通按钮，它背后站着微信这位非常讲规矩的门卫。证件、时机和用途少一个，门都不会开。

编辑表单的数据回显与提交：新增、修改和重提如何共用页面

Sat, 22 Aug 2026 00:00:00 GMT

同一张表单常常同时承担新增、修改和驳回重提。真正麻烦的不是给 input 填值，而是让接口字段、页面字段、枚举、日期、图片和提交模式保持一致。

1. 先明确三种模式#

1
const mode = computed(() => {
2
  if (isResubmitting.value) return 'resubmit'
3
  if (order.editingOrderId) return 'edit'
4
  return 'create'
5
})

模式决定标题、按钮文案、接口和部分校验，但不应改变字段本身的含义。

2. 回显函数是接口到表单的适配器#

1
function fillFromOrder(data = {}) {
2
  editingOrderId.value = data.orderId || null
3
  courierCompany.value = normalizeEnumValue(COURIER_COMPANY_OPTIONS, data.expressCompanyName)
4
  courierNo.value = data.expressNo || ''
5
  packageWeight.value = data.cargoWeightKg == null ? '' : Number(data.cargoWeightKg)
6
  packageVolume.value = data.cargoVolume == null ? '' : String(data.cargoVolume)
7
}

空值不能一律写成 0；否则用户会误以为服务端保存了 0。枚举值也要经过兼容转换，处理旧数据可能返回中文名称或历史编码的情况。

3. 日期时间回显#

接口时间可能包含 T、秒和时区，选择器需要的是固定格式。回显时统一截取，提交时再构造成完整日期时间：

1
arriveTime.value = data.expectedArriveTime
2
  ? String(data.expectedArriveTime).replace('T', ' ').trim().slice(0, 16)
3
  : ''

页面显示格式和接口传输格式应由两个函数明确转换，避免到处 slice。

4. 异步加载顺序#

编辑页面通常需要：订单详情、地址、枚举字典和凭证图片。订单详情与字典可以并行，表单回显完成后再处理依赖订单 ID 的凭证。

1
读取路由 orderId
2
   ↓
3
并行加载订单详情和字典
4
   ↓
5
fillFromOrder / fillFromAddress
6
   ↓
7
下载鉴权凭证并回显

页面显示 editingLoading，避免数据尚未回显时用户已经提交空表单。

5. 构造提交 payload#

回显与提交应成对出现：fillFromOrder 将服务端数据转成页面状态，buildCourierPayload 将页面状态转回接口模型。模板不参与字段拼装。

1
const response = mode.value === 'resubmit'
2
  ? await OrderApi.resubmitOrder(id, payload)
3
  : mode.value === 'edit'
4
    ? await OrderApi.updateOrder(payload)
5
    : await OrderApi.createOrder(payload)

6. 图片做差异提交#

已有远程图片与新选择的本地图片放在同一展示数组中，同时额外保存已有路径集合。提交时仅上传新增项，删除远程项时调用删除接口。它相当于一个小型 diff。

7. 表单状态清理#

页面提交成功或主动离开新建流程后，应清理 Store 中的编辑 ID、字段和图片；但从地图选点或地址簿返回时不能清理，否则用户之前填写的内容会丢失。

因此清理动作不能简单放在每次 onUnload，而要根据导航目的和成功状态执行。

8. 后端验证仍是最终防线#

前端校验用于即时反馈，API 层在提交前再次执行 normalize + validate，后端还要做最终业务校验。三层并不重复：页面重体验，API 层防调用遗漏，后端保数据安全。

9. 本篇小结#

表单回显的最高境界不是“看起来填上了”，而是用户不改任何字段也能安全提交，改一个字段只改变那一个事实。新增、修改、重提共用页面以后，我最大的愿望很朴素：别让上一张订单的照片偷偷跟着下一张订单去旅行。

地图坐标与轨迹渲染：管理端和小程序的共同实践

Fri, 21 Aug 2026 00:00:00 GMT

管理端使用 Web 地图，小程序使用原生 map，API 完全不同，但最常见的问题其实一致：数据字段不统一、坐标系不一致、图标锚点错误、缩放后覆盖物偏移，以及动画离开页面后没有停止。

1. 统一点模型#

先把所有来源转成最小模型：

1
type GeoPoint = {
2
  latitude: number
3
  longitude: number
4
}

1
function normalizePoint(source = {}) {
2
  const latitude = Number(source.latitude ?? source.lat ?? source.y)
3
  const longitude = Number(source.longitude ?? source.lng ?? source.lon ?? source.x)
4
  return Number.isFinite(latitude) && Number.isFinite(longitude)
5
    ? { latitude, longitude }
6
    : null
7
}

渲染层只接收 GeoPoint，不再猜字段。

2. 纬度和经度不要写反#

很多地图构造函数使用 (longitude, latitude)，数据模型通常写 { latitude, longitude }。封装一次转换：

1
const toLngLat = point => new T.LngLat(point.longitude, point.latitude)

不要在十几个调用点手写参数顺序。

3. 坐标系#

飞行航线可能是 WGS84，国内互联网地图常显示 GCJ-02。整体偏移数百米时，优先检查坐标系，不要先调 CSS。转换只执行一次，并让接口或配置明确声明来源坐标系。

4. 覆盖物与普通 DOM 的边界#

随地图缩放和拖动的元素必须由地图引擎管理：marker、polyline、circle。普通 DOM 适合标题、按钮和说明卡片，不适合表示无人机位置。

1
地理对象：经纬度 → 地图引擎 → 屏幕像素
2
普通元素：CSS 像素 → 页面布局

两套坐标系统一不了，硬叠在一起就会产生“悬浮”。

5. 锚点#

marker 的坐标对应图片中的哪个点，由 anchor 决定。普通水滴图标常用 { x: 0.5, y: 1 }，无人机图标可能更适合中心或机身下方。素材带透明边距时，视觉中心和图片中心还不相同，需要按实际资源微调。

6. 路线插值#

沿折线运动不能简单在起终点之间插值，否则会穿过拐角。先计算每段距离和总距离，再把整体进度映射到某一段：

1
整体进度 × 总距离 = 已飞距离
2
已飞距离 - 前序线段长度 = 当前段距离
3
当前段距离 / 当前段长度 = 当前段进度

最后只在当前段起终点之间插值。

7. 视野适配#

Web 地图使用 bounds，小程序使用 includePoints。padding 要考虑侧栏、底部卡片和顶部标题，不能只让所有点“理论上可见”。

8. 实时位置和推算位置#

实时接口有坐标时优先显示真实位置；只有缺少实时点时，才根据开始时间和预计时长推算。页面要明确这是推算进度，不能把动画当成真实遥测。

9. 生命周期#

离开页面时停止动画帧和轮询、移除事件、清理覆盖物。重新加载航线前也先停止旧动画，否则两套任务会争夺同一个 marker。

10. 排查顺序#

遇到偏移时依次检查：

经纬度是否写反；
坐标是否有效；
WGS84/GCJ-02 是否一致；
元素是否为地图 marker；
anchor 是否正确；
素材是否有透明留白；
路线和 marker 是否使用同一批转换后坐标。

11. 本篇小结#

地图 bug 经常看起来像“差十几个像素”，根因却可能远在坐标系。建立统一点模型和排查顺序以后，我终于不用围着无人机图标反复改 margin-top 了——它该在经纬度里飞，不该在 CSS 里漂。

图片上传与鉴权预览：订单凭证的完整链路

Thu, 20 Aug 2026 00:00:00 GMT

项目中图片出现得很频繁：下单要上传订单和货品照片，签收要查看凭证，异常反馈要上传证据，个人中心还要维护头像。它们都叫“图片”，但业务类型、访问权限和生命周期并不相同。

1. 图片类型先于文件路径#

订单凭证通过 proofType 区分：

类型	用途
`ORDER_PHOTO`	订单或平台截图
`GOODS_PHOTO`	货品实物照片
`SIGN_PHOTO`	签收凭证
`EXCEPTION_FEEDBACK`	异常证据

文件路径只说明图片在哪里，凭证类型才说明它在业务中代表什么。

2. 选择图片#

小程序统一封装 wx.chooseMedia，页面只获得本地临时路径数组。取消选择不是错误，不弹失败提示；真正的权限或文件错误才提醒用户。

1
const remain = Math.max(0, 9 - images.value.length)
2
const selected = await chooseImages({ count: remain })
3
images.value.push(...selected)

数量上限应在选择前计算，避免选择完成后再粗暴截断。

3. 上传依赖业务主键#

新订单尚无 orderId，所以流程必须分两阶段：

1
提交订单 JSON
2
    ↓ 获得 orderId
3
上传 multipart 图片并携带 orderId、proofType、sortNo

不同类型可以组成任务数组并行上传：

1
const tasks = files.map((filePath, index) =>
2
  DeliveryApi.uploadProof(filePath, { orderId, proofType, sortNo: index + 1 })
3
)
4
await Promise.all(tasks)

若业务要求原子性，后端还需要提供回滚或草稿机制；前端不能假设第二阶段永远成功。

4. 编辑时区分远程图与新文件#

编辑订单先通过鉴权接口把已有凭证下载为临时地址，并记录在 existing...Files 中。提交时只上传新增文件：

1
const newFiles = currentFiles.filter(path => !existingFiles.includes(path))

如果把所有回显图再次上传，用户每编辑一次备注，凭证就复制一遍。

5. 删除已有图片#

本地新图片可以直接从数组移除；服务端已有凭证必须调用删除接口。删除成功后重新获取凭证列表，失败则保留图片和错误提示，不能让页面与服务端各自认为不同结果。

6. 鉴权图片不能直接写 URL#

订单凭证和头像需要 Authorization。小程序 <image> 标签无法方便地为 URL 加自定义 header，因此 getAuthenticatedImage 先下载文件并返回临时路径。

1
const tempPath = await getAuthenticatedImage('/manage/user/avatar', {
2
  cacheKey: 'current-user-avatar',
3
  force: true
4
})

管理端则由 AuthenticatedImage 组件统一请求 Blob、生成 Object URL，并处理加载与释放。

7. 缓存与竞态#

头像适合按用户缓存，订单凭证可以按 proof ID 缓存。更新后必须使旧缓存失效。并发刷新时还要防止旧请求晚返回覆盖新图片，Auth Store 使用串行 Promise 链解决这一问题。

8. 失败体验#

单张预览失败应显示占位和重试，不能让整个详情页失败；批量提交时则要明确哪些图片失败。图片压缩、格式和大小限制最好在选择后立即检查，而不是上传数秒后才告诉用户。

9. 本篇小结#

图片功能并不止“选一张再传上去”。类型、主键、鉴权、缓存、回显和删除组成了完整生命周期。照片虽然不会说话，但如果 proofType 传错了，它确实会把业务讲成另一个故事。

分页懒加载与前端并发控制

Wed, 19 Aug 2026 00:00:00 GMT

列表从 20 条增长到 2000 条以后，“一次全拿”会越来越慢。分页本身不难，难的是刷新、追加、搜索和快速切换同时发生时，列表仍然不重、不乱、不倒退。

1. 基础分页状态#

1
const rows = ref([])
2
const pageNum = ref(1)
3
const pageSize = 20
4
const total = ref(0)
5
const loading = ref(false)
6
const loadingMore = ref(false)
7
const hasMore = computed(() => rows.value.length < total.value)

hasMore 根据实际已加载数量判断，比单纯判断“这一页是否满 20 条”更可靠。

2. 下拉刷新和触底追加#

刷新永远请求第一页并替换旧列表；追加请求下一页并合并：

1
const targetPage = reset ? 1 : pageNum.value + 1
2
const response = await fetchList({ pageNum: targetPage, pageSize })
3
rows.value = reset ? response.rows : mergeUnique(rows.value, response.rows)
4
pageNum.value = targetPage

只有请求成功后才更新 pageNum。如果先加页码再请求，失败重试会跳过一页。

3. 请求锁#

1
if (loading.value || loadingMore.value) return
2
if (!reset && !hasMore.value) return

触底事件可能在短时间触发多次，锁可以避免同一页被重复追加。按钮 disabled 只是表现层，方法内部仍要判断。

4. 去重#

时间倒序列表在分页期间可能插入新记录，导致第二页包含第一页末尾的数据。用稳定主键去重：

1
function mergeUnique(current, incoming) {
2
  const map = new Map()
3
  current.concat(incoming).forEach(item => map.set(String(item.id), item))
4
  return [...map.values()]
5
}

如果没有单一 ID，可以使用业务组合键，但要保证稳定。

5. 重新排序#

消息列表合并后按 sendTime 倒序，异常列表按 createTime 倒序。日期字符串先做跨端兼容解析，解析失败的记录放在末尾。排序只影响展示，不修改分页请求的服务端排序口径。

6. 查询竞态#

用户从“全部”快速切到“配送中”，旧请求可能晚返回。使用版本号：

1
let queryVersion = 0
2
async function query() {
3
  const version = ++queryVersion
4
  const result = await fetchList(currentParams.value)
5
  if (version !== queryVersion) return
6
  rows.value = result.rows
7
}

或者使用 AbortController/小程序 request task 取消旧请求。取消适合节省资源，版本号适合保证最终一致，两者可以组合。

7. 页面生命周期#

一级页面常在 onShow 刷新最新数据，详情返回时列表即可更新；但不要在 onShow、onMounted 和下拉刷新中同时无条件请求。明确唯一首次加载入口，再由用户动作触发其他刷新。

8. 空态与底部提示#

列表需要区分首次加载、真正为空、加载更多、已加载全部和失败重试。一个永远显示“暂无数据”的页面，会把网络失败伪装成业务空数据。

9. 本篇小结#

懒加载的目标不是把 2000 条切成 100 次请求，而是让用户先看到最新内容，并且往下找时自然接上历史。列表如果会重复、跳页和回滚，再勤快的“加载更多”也只是多制造一点混乱。

状态驱动的前端页面设计：让按钮、标签和流程保持一致

Tue, 18 Aug 2026 00:00:00 GMT

订单和异常模块有一个共同特点：同一条数据在不同状态下，颜色、文案、按钮和下一步都不同。若把规则散在几十个 v-if 中，页面迟早会出现“显示待调度，却还能再次审核”的矛盾。

1. 原始状态与展示状态分开#

服务端状态是业务事实，页面标签是面向用户的分组。小程序把多个后台终态归入“已完成”标签，但卡片仍显示“已取消”“已驳回”等具体状态。

1
const historyStates = new Set([
2
  'COMPLETED', 'CANCELED', 'REJECTED', 'DELIVERY_FAILED'
3
])

分组用于筛选，原始状态用于解释，二者不能互相覆盖。

2. 状态元数据表#

1
const ORDER_STATUS_META = {
2
  UNPAID: { label: '待支付', tone: 'danger' },
3
  PENDING_AUDIT: { label: '待审核', tone: 'warning' },
4
  WAIT_DISPATCH: { label: '待调度', tone: 'success' },
5
  DELIVERING: { label: '配送中', tone: 'primary' },
6
  COMPLETED: { label: '已完成', tone: 'info' }
7
}

列表、详情和消息卡片从同一份元数据读取文案与色彩。未知状态必须有安全回退，而不是渲染空白。

3. 操作白名单#

按钮应从“当前状态允许什么”推导：

1
const ACTIONS_BY_STATUS = {
2
  PENDING_AUDIT: ['approve', 'reject'],
3
  WAIT_DISPATCH: ['cancel', 'startFlight'],
4
  DELIVERING: ['markDelivered', 'markFailed']
5
}
6

7
const can = action => (ACTIONS_BY_STATUS[status.value] || []).includes(action)

前端白名单改善体验，后端仍要再次校验状态，防止重复请求或越权调用。

4. 派生状态不要重复保存#

“是否历史订单”“是否可以支付”“异常处于登记还是跟踪阶段”都可以由原始数据计算：

1
const stage = computed(() => ticket.value?.resultOrderId
2
  ? 'tracking'
3
  : 'registration')

如果同时保存 stage 和 resultOrderId，其中一个更新失败就会产生矛盾。能计算出来的状态尽量用 computed。

5. 操作后重新获取事实#

审核、支付、取消或完成配送后，不只修改本地 status，而是重新读取详情。一次后端动作可能同时生成流程日志、任务和通知，本地只改一个字段无法覆盖全部副作用。

6. 终态与中间态#

终态通常只读，中间态允许继续操作。异常流程还存在派生订单，使“原订单终态”不等于“异常处理结束”。状态设计要围绕业务对象分别判断，不能拿订单状态替代工单状态。

7. 状态文案也属于规则#

同一个值在用户端与管理端可以有不同表达，例如后台“待审核”对用户可解释为“订单已提交，等待平台确认”。枚举值保持一致，展示文案根据角色转换。

8. 本篇小结#

状态驱动并不是把 if 换成对象，而是承认页面行为来自业务状态。规则集中以后，按钮不再各有各的想法，整个页面终于像同一个团队开发的——哪怕这个团队其实就是昨天和今天的我。

前端开发场景中如何对接后端接口拿到需要的数据

Mon, 17 Aug 2026 00:00:00 GMT

“调接口拿数据”听起来只有一行 await，实际包含请求参数、身份认证、错误处理、响应适配、关联数据补全和页面状态。项目两端使用不同请求工具，但方法论是一致的。

1. API 层不等于页面层#

管理端把订单接口集中在 src/api/manage/deliveryOrder.js，小程序放在 api/business/order.js。页面调用有业务名称的方法：

1
OrderApi.getOrderDetail(orderId)
2
OrderApi.resubmitOrder(orderId, payload)
3
DeliveryOrderApi.startFlight(orderId, params)

页面不应反复拼 URL，也不应关心 token header。接口路径变化时只改 API 层。

2. 请求层统一处理公共问题#

小程序 utils/request.js 统一完成：

baseURL 与查询参数拼接；
Authorization 注入；
401 刷新与登录引导；
请求超时和错误消息；
loading 引用计数；
相同请求取消和防重复。

1
export const get = (url, params = {}, options = {}) =>
2
  request({ ...options, url, method: 'GET', params })

统一层只处理通用协议，不要在这里写“订单失败后跳订单页”这种业务逻辑。

3. 先设计页面所需模型#

对接前先列出页面真正需要的字段。例如异常卡片需要异常编号、业务订单号、描述、级别、状态和时间。接口若只返回 orderId，就应明确缺少的是业务订单号，而不是稀里糊涂把 ID 显示出来。

1
页面字段清单
2
   ↓ 对照
3
接口响应字段
4
   ↓ 找差异
5
补充接口 / 后端联表 / 前端补全

这一步能提前发现“N+1 查询”或业务标识缺失。

4. 查询参数与空值#

筛选表单不要把空字符串、undefined 和无效日期全部传给后端。请求层序列化时跳过空值，页面在点击查询时把页码重置为 1。

1
Object.entries(params).forEach(([key, value]) => {
2
  if (value === undefined || value === null || value === '') return
3
  // append query
4
})

排序字段也应显式传递，例如 orderByColumn: 'createTime'、isAsc: 'desc'，避免依赖数据库默认顺序。

5. 响应适配#

接口可能返回 { data }、{ rows, total } 或直接对象。API/Store 层先归一，模板只消费确定类型：

1
const rows = Array.isArray(response?.rows) ? response.rows : []
2
const total = Number(response?.total ?? rows.length)
3
const detail = response?.data || response || {}

模板里大量 response?.data?.rows ?? response?.rows 是接口边界没有收好的信号。

6. 关联数据补全#

异常与通知接口只返回 orderId 时，前端可以并行查询订单详情：

1
const ids = [...new Set(rows.map(item => item.orderId).filter(Boolean))]
2
const results = await Promise.allSettled(ids.map(id => getOrderDetail(id)))

补全结果用 Map 缓存，避免同一订单重复请求。不过从长期看，列表接口直接返回 orderNo 更合理，因为这是稳定且高频的展示字段。

7. 并行还是串行#

互不依赖的详情、凭证和日志可以并行；创建订单后上传凭证必须串行两个阶段；取消飞行任务后退款也必须按业务顺序执行。

1
并行：订单详情 ┬ 凭证
2
              ├ 历史
3
              └ 日志
4

5
串行：创建订单 → 得到 orderId → 上传凭证

是否并行取决于依赖关系，不取决于“Promise.all 看起来更快”。

8. 错误边界#

核心数据失败时页面显示错误和重试；附属数据失败时用 Promise.allSettled 保留其余内容。写操作失败应保留表单输入，不自动假装成功。

9. 请求竞态与取消#

搜索、标签切换、周期切换都可能产生竞态。可以使用版本号忽略旧响应，或由请求层取消完全相同的前一个任务。两者解决的问题不同：版本号处理“不同参数的返回顺序”，去重取消处理“同参数重复触发”。

10. 本篇小结#

接口对接的终点不是控制台打印出数据，而是页面在慢网、空值、旧响应和局部失败下仍然可信。await 只有五个字母，它身后的活可一点都不少。

小程序开发日记⑧：订单轨迹与无人机位置

Sat, 15 Aug 2026 00:00:00 GMT

“查看位置”页面需要让用户看到起点、目的地、航线和无人机进度。它看起来比管理端地图简单，实际还多了小程序原生地图、坐标系和真机缩放等限制。

1. 航点兼容解析#

后端航线可能是数组、JSON 字符串，也可能嵌套在 waylinePoints、routePoints 或 coordinates 中。页面先收集候选，再统一解析：

1
function normalizePointItem(item = {}) {
2
  const source = item.point || item.location || item.coordinate || item.position || item
3
  return normalizePoint(
4
    source,
5
    ['latitude', 'lat', 'waylineLatitude', 'pointLatitude', 'y'],
6
    ['longitude', 'lng', 'lon', 'waylineLongitude', 'pointLongitude', 'x']
7
  )
8
}

只有有限数字组成的点才进入航线，避免一个空字符串让整条 polyline 消失。

2. WGS84 与 GCJ-02#

飞行系统常使用 WGS84，小程序地图使用 GCJ-02。页面根据接口标记判断是否转换：

1
function normalizeMapRoutePoints(points, data) {
2
  return shouldConvertRouteToGcj02(data)
3
    ? points.map(wgs84ToGcj02)
4
    : points
5
}

坐标系不一致时，路线会整体偏移，常被误判为无人机图标锚点问题。排查地图偏移应先确认坐标系，再看图标样式。

3. marker 必须绑定地理坐标#

起点、终点和无人机都通过地图 markers 属性创建：

1
function buildMarker(id, point, iconPath, width, height, options = {}) {
2
  return {
3
    id,
4
    latitude: point.latitude,
5
    longitude: point.longitude,
6
    iconPath,
7
    width,
8
    height,
9
    anchor: options.anchor || { x: 0.5, y: 1 }
10
  }
11
}

无人机图标需要根据素材透明区域调整 anchor。若使用普通 image 绝对定位在地图上，缩放后路线和图片分别处于地理坐标与屏幕像素两个体系，必然发生悬浮偏移。

4. 航线与飞行进度#

页面使用各线段球面距离计算累计长度，再根据整体进度找到无人机位置：

1
function pointAtRoute(points, progress) {
2
  const distances = points.slice(1).map((p, i) => distanceBetween(points[i], p))
3
  const target = distances.reduce((a, b) => a + b, 0) * progress
4
  // 找到 target 所在线段，再在线段内插值
5
}

飞行进度优先使用任务开始时间与持续时间计算；无有效任务时间时使用接口当前位置或稳定的展示进度。页面不能每次刷新都让无人机回到起点。

5. 自动适配视野#

当航点不少于两个时调用 includePoints：

1
mapContext.includePoints({
2
  points: routePoints,
3
  padding: [72, 48, 180, 48]
4
})

底部信息卡较高，所以底部 padding 大于其他方向，防止终点被卡片挡住。没有有效航线时才使用默认中心与缩放级别。

6. 动画与刷新#

动画通过 requestAnimationFrame 或定时帧更新 marker 的坐标。下拉刷新重新读取任务后先停止旧动画，再应用新航线并重启动画。页面卸载时同样停止，避免后台继续计算。

1
onUnload(() => stopRouteAnimation())

7. 当前定位不是无人机定位#

页面的“定位到我”调用 moveToLocation，只移动地图视野到用户当前位置，不会修改无人机 marker。把用户定位与飞行位置分开命名，可以避免业务含义混淆。

8. 本篇小结#

真机与开发者工具差异#

原生 map 的 marker 锚点、图片清晰度和 includePoints 行为在开发者工具与真机上可能略有差异。因此素材使用合适的实际尺寸，不依赖超大透明画布；padding 预留安全区；图标问题优先检查素材边界和 anchor，而不是只看模拟器结果。

数据新鲜度#

轨迹页显示“更新时间”，下拉刷新后重新获取任务。若长时间没有新位置，页面标注“位置更新延迟”，而不是继续播放无限逼真的动画。用户需要知道无人机大概在哪，也需要知道这个位置有多新。

路线接口为空时，只有起终点就绘制基础线；连起终点都不完整时展示明确空态。使用演示航线应仅限开发环境，正式页面不能用一条漂亮的假路线掩盖数据缺失。

地图放大后图标会不会飘，答案不在 top: -20px，而在坐标系、marker 和 anchor。修复这类问题让我学会先问一句：这个元素究竟属于地图，还是只是盖在地图上？问对了，偏移通常就解决了一半。

小程序开发日记⑦：服务范围、收货地址与地图选点

Fri, 14 Aug 2026 00:00:00 GMT

无人机并不是“哪里都能送”。用户下单前需要知道服务覆盖到哪里，填写地址时又需要把文字地点落到真实坐标。本篇包含服务范围和地图选点两部分。

1. 服务范围数据#

pages/common/service-range.vue 从配置接口获取中心纬度、经度和半径。接口不可用时页面显示“程序未配置”，开发环境可以保留默认中心用于布局，但不能把默认值当真实范围。

1
function applyServiceArea(area) {
2
  latitude.value = area.latitude
3
  longitude.value = area.longitude
4
  serviceRadius.value = area.radius
5
  mapScale.value = getScaleByRadius(area.radius, area.latitude)
6
  mapReady.value = true
7
}

地图的 circles 属性绘制服务区域：

1
const circles = computed(() => [{
2
  latitude: latitude.value,
3
  longitude: longitude.value,
4
  radius: serviceRadius.value,
5
  color: '#1769e8',
6
  fillColor: '#1769e833',
7
  strokeWidth: 3
8
}])

2. 根据半径计算缩放级别#

固定 scale 会让小范围太空、大范围被裁掉。页面根据半径估算目标米/像素，再换算缩放级别：

1
function getScaleByRadius(radius, lat) {
2
  const targetMetersPerPixel = Math.max(1, (radius * 2) / (390 * 0.72))
3
  const cosLat = Math.max(0.2, Math.cos(Number(lat) * Math.PI / 180))
4
  const scale = Math.log2((156543.03392 * cosLat) / targetMetersPerPixel)
5
  return Math.max(5, Math.min(16, Math.round(scale)))
6
}

纬度会影响同一缩放级别下的地面分辨率，因此计算中保留 cos(lat) 修正。

3. 地图选点页面#

pages/common/location-picker.vue 支持当前位置、地点搜索、拖动地图中心和候选地址列表。地图中间的选点图标是固定在容器中心的视觉指示，真正坐标在 regionchange 结束时通过地图上下文解析。

1
用户拖动地图
2
   ↓
3
regionchange end
4
   ↓
5
读取地图中心经纬度
6
   ↓
7
逆地理编码获得地址
8
   ↓
9
更新候选地点与选中项

拖动过程中不应连续逆地理编码，否则一次手势会产生大量请求。页面通过序号和短延迟，只处理最后一次中心点变化。

4. 候选地点模型#

无论候选数据来自搜索、当前位置还是地图中心，都统一转换为：

1
{
2
  id,
3
  title,
4
  subtitle,
5
  fullAreaName,
6
  detailedAddress,
7
  regionId,
8
  latitude,
9
  longitude
10
}

统一模型使列表选择和地图选择最终都调用 recipient.setSelectedAddress(place)，不用为每种来源写一套回填逻辑。

5. 确认前再次检查服务范围#

选择一个地点不代表它一定可配送。确认按钮拿到坐标后调用服务范围判断，超出范围则保留页面并给出提示。校验要在最终坐标确定后执行，而不是只在搜索结果返回时判断，因为用户还可能继续拖动地图。

6. 原生地图与覆盖层#

小程序 map 是原生组件，层级和普通 DOM 不完全相同。地图上的 marker、polyline、circle 尽量使用组件原生属性；普通说明卡片放在地图外层。需要覆盖地图的按钮要控制层级，并在真机环境关注 cover-view 兼容性。

7. 定位权限与降级#

“定位到我”使用 GCJ-02 坐标。用户拒绝位置权限时不阻断页面，仍可搜索或拖动地图选择；页面只提示检查权限。定位是快捷方式，不应成为唯一入口。

8. 本篇小结#

范围判断的计算#

圆形服务区可以使用 Haversine 公式计算选点到中心的球面距离，再和半径比较。页面显示的圆与提交校验必须使用同一组中心和半径，不能一个来自默认配置、另一个来自接口。

1
const inRange = distanceMeters(point, serviceCenter) <= serviceRadius

靠近边界时要考虑 GPS 精度和业务容差，页面可以显示“接近服务边界，请确认”，最终是否允许下单由后端再次判断。前端范围校验用于即时反馈，不能替代服务端规则。

逆地理编码结果中的省市区 ID、完整地区名和 POI 文本分别保存，避免把一整串可读地址错误地当成行政区字段提交。

文字地址让人知道去哪儿，经纬度让程序知道画在哪儿，服务半径则负责说“能不能去”。三者对齐以后，下单地址才不再是一句模糊的地名，而是地图上一个可以被验证的点。

小程序开发日记⑥：地址簿与收货信息复用

Thu, 13 Aug 2026 00:00:00 GMT

无人机配送的地址不只是“某某路多少号”，还包括船名、MMSI、收货人、手机号、区域和经纬度。地址簿的任务，就是把这一整组信息保存成可复用的业务对象。

1. 管理模式与选择模式#

pages/profile/address-book.vue 通过路由参数支持两种模式：

1
onLoad(options => {
2
  pageMode.value = options.mode === 'select' ? 'select' : 'manage'
3
})

管理模式：新增、编辑、删除、设为默认；
选择模式：从下单页进入，点击地址后写入 recipientStore 并返回。

一套列表复用两种场景，但按钮与交互目标清晰分开。

2. 地址数据结构#

recipientStore 管理以下字段：

1
const addressId = ref(null)
2
const shipName = ref('')
3
const shipMmsi = ref('')
4
const recipientName = ref('')
5
const recipientPhone = ref('')
6
const fullAreaName = ref('')
7
const detailedAddress = ref('')
8
const regionId = ref(null)
9
const longitude = ref(null)
10
const latitude = ref(null)

Store 的价值在于地址选择页与下单页之间不需要把十个字段都拼进 URL，也避免页面返回后数据丢失。

3. 服务端字段归一化#

不同接口可能使用 vesselName、receiverName，页面表单则使用更贴近交互的 shipName、recipientName。fillFromAddress 负责回显，buildAddressPayload 负责提交：

1
function fillFromAddress(address = {}) {
2
  addressId.value = address.addressId || address.id || null
3
  shipName.value = address.vesselName || ''
4
  shipMmsi.value = address.mmsi || ''
5
  recipientName.value = address.receiverName || ''
6
  recipientPhone.value = address.receiverPhone || ''
7
  longitude.value = address.longitude ?? null
8
  latitude.value = address.latitude ?? null
9
}

这层转换让模板不必同时理解两套命名。

4. 搜索与列表加载#

地址列表进入页面时加载，搜索支持收货人、手机号、船名和 MMSI。频繁输入时应避免每个字符都触发无意义请求，可以在页面端防抖，或在点击搜索时统一提交关键词。

空搜索恢复完整列表，删除后重新加载服务端数据，避免只删本地数组造成分页总数和默认状态不一致。

5. 默认地址#

设为默认成功后，页面把当前记录标为默认，同时清除其他记录的默认标记：

1
const applyDefaultFlag = item => ({
2
  ...item,
3
  isDefault: String(item.addressId) === String(targetId) ? '1' : '0'
4
})
5

6
addressList.value = addressList.value.map(applyDefaultFlag)

新建订单时优先加载默认地址，让高频用户无需重复选择。默认地址不存在时再保留空表单，不随便取列表第一条。

6. 删除确认#

地址删除是不可逆业务操作，页面先弹确认框，再调用删除接口。若被订单引用，后端应按业务规则拒绝或只做逻辑删除；前端展示明确错误，不擅自从列表隐藏。

7. 地址表单校验#

收货人手机号、MMSI、船名、详细地址和经纬度分别校验。尤其经纬度不能只判断“非空”，还要转为有限数字：

1
const validCoordinate = value => Number.isFinite(Number(value))

地图选点返回坐标后，表单仍允许用户补充更具体的地址描述。地理坐标负责计算，文字地址负责阅读，两者缺一不可。

8. 本篇小结#

选择地址后的返回策略#

选择模式中点击整张卡片写入 Store，再调用 navigateBack。编辑按钮必须阻止事件冒泡，否则用户只是想改地址，却会先把它选中并返回。管理模式则不响应整卡选择，只开放明确的编辑、默认和删除入口。

地址变更与历史订单#

修改地址簿记录不应修改已经创建的历史订单。下单时把地址快照写进订单，地址簿只负责为新订单提供默认值。否则用户改了手机号，三个月前的订单详情也跟着变化，历史凭证就失去真实性。

地址列表接口返回空值或坐标缺失时，卡片仍可展示基础信息，但选中下单前必须再次校验完整性。管理页允许修复不完整旧数据，业务提交页则坚持严格校验。

地址簿减少的不是几次打字，而是下单时一整组高风险信息的重复录入。船名少一个字可能只是难看，MMSI 或坐标错一位可就完全是另一艘船。能复用的数据，还是让系统多记一点，人脑少背一点。

小程序开发日记⑤：异常反馈与处理结果

Wed, 12 Aug 2026 00:00:00 GMT

配送发生问题时，用户需要的不只是一个文本框，而是一条能够被管理端识别、处置和回告的异常链路。异常反馈模块连接了订单、图片凭证、异常工单与处理结果。

1. 反馈类型与后端异常类型#

页面提供未收到、破损、少件错件、位置错误、取消申请和其他问题。前端枚举通过 EXCEPTION_TYPE_MAP 转为后端工单类型：

1
const exceptionType = EXCEPTION_TYPE_MAP[feedbackType.value]
2
if (!exceptionType) {
3
  uni.showToast({ title: '异常类型映射失败', icon: 'none' })
4
  return false
5
}

把映射放在常量文件中，可以让表单、列表和消息详情共享同一种解释。

2. 动态校验规则#

并不是所有反馈都强制上传图片。包裹破损和位置错误需要至少一张证据图，其余类型允许只填写描述：

1
const evidenceReady = !['DAMAGED', 'WRONG_LOCATION'].includes(type)
2
  || images.value.length > 0

描述还要经过长度和空白字符校验。动态规则既减少普通问题的提交阻力，也保证需要现场判断的问题有足够证据。

3. 先上传证据，再创建工单#

异常证据仍复用订单凭证接口，凭证类型为 EXCEPTION_FEEDBACK：

1
for (const [index, filePath] of images.value.entries()) {
2
  await DeliveryApi.uploadProof(filePath, {
3
    orderId,
4
    proofType: DELIVERY_PROOF_TYPES.EXCEPTION_FEEDBACK,
5
    sortNo: index + 1
6
  })
7
}
8

9
await AbnormalApi.submitFeedback({
10
  orderId,
11
  exceptionType,
12
  exceptionFeedback: exceptionType,
13
  description
14
})

Store 使用 ${orderId}:${filePath} 作为本次会话的上传键，防止提交重试时同一张图片被重复上传。移除图片时同步清除对应缓存键。

4. 只能关联真实订单#

反馈页加载用户订单供选择，并要求 orderId 是有效数字。页面展示订单号、创建时间和服务类型，提交时才使用主键关联。显示层与提交层的标识不能混淆。

1
const normalizedOrderId = /^\d+$/.test(String(orderId || ''))
2
  ? String(orderId)
3
  : ''

5. 异常历史分页#

feedback-list.vue 每页读取 10 条，触底追加历史记录，并以 exceptionId 去重：

1
function mergeUniqueFeedback(current, incoming) {
2
  const map = new Map()
3
  current.concat(incoming).forEach(item => {
4
    map.set(String(item.exceptionId), item)
5
  })
6
  return [...map.values()]
7
}

列表显示异常类型、处理状态、描述、优先级、异常编号、提交时间以及管理端填写的处理结果。

6. 关联订单号补全#

异常接口可能只返回 orderId。列表先使用响应中的 orderNo，缺失时并行查询订单详情，并缓存 orderId -> orderNo：

1
const results = await Promise.allSettled(
2
  uniqueOrderIds.map(id => OrderApi.getOrderDetail(id, { showError: false }))
3
)

某一订单读取失败不会阻塞整页，最后才退化显示 --。这次处理让我更明确：数据库主键解决关联，业务订单号解决沟通。

7. 提交状态与表单复位#

提交期间禁用按钮和上传区，成功后调用 reset() 清理类型、描述、图片与上传缓存，再返回异常列表。失败时保留用户填写内容，避免网络波动让用户重新打字。

8. 本篇小结#

异常与订单状态相互独立#

异常工单处于“处理中”，不代表订单一定是“配送中”；订单完成后仍可能提交破损反馈。列表分别展示订单号和异常处理状态，避免用订单状态替代工单进度。管理端关闭工单后，用户端通过刷新读取 processResult，形成回告闭环。

证据上传失败的处理#

证据上传成功但工单提交失败时，重新提交会利用本地上传键跳过已成功图片，减少重复文件。更完善的服务端可以提供临时上传会话或在创建工单时一次性绑定 proof IDs，从根本上保证一致性。

反馈列表加载订单号时维护缓存，后续页出现相同订单不再查询。退出账号时清空缓存，避免不同用户之间复用关联信息。

异常反馈不是“意见箱”，而是配送流程的补充入口。证据要能追到订单，处理结果要能回到用户。把这条链路打通以后，异常终于不再只是客服聊天记录里的一句“我再帮您看看”。

小程序开发日记④：消息推送与消息中心

Tue, 11 Aug 2026 00:00:00 GMT

消息模块既要面对微信订阅消息，也要维护小程序自己的消息中心。推送负责把用户叫回来，站内消息负责把事情说清楚，两者不能只完成其中一半。

1. 消息分页模型#

store/modules/message.js 保存列表、当前消息、分页与加载状态：

1
const messages = ref([])
2
const pageNum = ref(1)
3
const pageSize = 20
4
const total = ref(0)
5
const loading = ref(false)
6
const loadingMore = ref(false)
7
const hasMore = computed(() => messages.value.length < total.value)

下拉刷新请求最新第 1 页，触底后请求下一页。每页 20 条既避免首次加载过重，也让历史消息可以逐步展开。

2. 刷新与加载更多不能混用状态#

1
async function load(reset = false) {
2
  if (loading.value || loadingMore.value) return
3
  if (!reset && !hasMore.value) return
4

5
  const targetPage = reset ? 1 : pageNum.value + 1
6
  reset ? loading.value = true : loadingMore.value = true
7
  // 请求并合并
8
}

两个 loading 分开后，页面可以在刷新时显示顶部状态，在追加历史消息时只显示底部“加载更多”，不会整页闪回骨架屏。

页面使用 scroll-view：

1
<scroll-view
2
  scroll-y
3
  refresher-enabled
4
  :refresher-triggered="refreshing"
5
  @refresherrefresh="refreshMessages"
6
  @scrolltolower="loadMore"
7
>

3. 去重与排序#

刷新与分页期间，服务端可能刚好插入新消息，导致相邻页数据发生位移。Store 使用 notificationId 合并去重，再按发送时间倒序：

1
const merged = new Map()
2
;(reset ? rows : messages.value.concat(rows)).forEach(item => {
3
  merged.set(String(item.notificationId), item)
4
})
5
messages.value = [...merged.values()].sort(sortBySendTimeDesc)

这比简单 concat 更能抵抗分页边界变化。

4. 已读状态的本地兜底#

接口暂未提供完整已读写回能力时，消息中心使用本地集合保存已读 ID：

1
const locallyReadIds = ref(new Set(uni.getStorageSync('readNotificationIds') || []))
2

3
function markMessageRead(id) {
4
  locallyReadIds.value.add(String(id))
5
  uni.setStorageSync('readNotificationIds', [...locallyReadIds.value])
6
}

加载列表时再把本地状态覆盖到消息对象。它不是最终的多端同步方案，但能保证同一设备上返回列表后红点不会复活。

5. 冷启动进入消息详情#

微信通知可能直接打开详情页，此时 Pinia 中没有缓存消息，而接口文档又没有单条详情接口。当前实现按较大页逐页查找目标 ID：

1
while ((page - 1) * pageSize < total) {
2
  const response = await getNotificationList({ pageNum: page, pageSize: 100 })
3
  const found = response.rows.find(item => String(item.notificationId) === targetId)
4
  if (found) return found
5
  total = Number(response.total)
6
  page += 1
7
}

这是兼容方案。更理想的后端能力是提供 /notification/{id}，这样消息历史很多时不会为了找一条记录扫描多页。

6. 关联订单显示业务订单号#

消息卡片和详情中的“关联订单”优先展示 orderNo，不能把数据库自增 orderId 当订单号。若通知只返回 ID，则额外读取订单详情进行补全。用户联系客服时说的是业务订单号，内部主键对他没有意义。

7. 订阅消息的定位#

小程序通过 wx.requestSubscribeMessage 请求用户授权，模板 ID 由统一工具封装。订阅请求应在用户主动操作后触发，例如下单成功、开启配送提醒，而不能在页面加载时强行弹窗。

站内消息作为事实记录，订阅消息作为触达渠道。即使用户拒绝订阅，消息中心仍应能查看状态变化。

8. 本篇小结#

未读数的口径#

当前列表只加载部分历史消息时，直接对 messages 数组计数只能得到“已加载消息中的未读数”，不一定等于账号全部未读。更完善的接口应单独返回 unreadTotal，底部导航红点使用总数，列表内部仍使用本地状态渲染单条消息。

推送打开后的路由恢复#

订阅消息携带 notificationId 或业务订单号，小程序冷启动时先完成登录态恢复，再进入详情。若消息不存在，页面显示可返回、可重试的错误状态；若关联订单已删除或无权限，只展示消息正文，不让整个详情失效。

消息内容还需要按类型决定动作按钮：订单状态通知可以查看订单，异常处置通知可以查看反馈结果，纯系统公告则没有业务跳转。按钮由消息类型映射生成，不能靠正文关键词猜测。

消息中心最开始只有 20 条时，看起来像是接口少给了点；补上刷新、分页、去重和冷启动后，它才像一个真正能用的收件箱。消息不一定都让人开心，但至少不能让人找不到。

小程序开发日记③：个人中心、登录与资料维护

Mon, 10 Aug 2026 00:00:00 GMT

个人中心看起来是头像加几行菜单，背后却集中了身份、授权、资料同步和登录过期处理。本篇把“我是谁”这件事从页面一直追到请求层。

1. 未登录与已登录是两套体验#

未登录用户可以浏览一级页面，但访问地址簿、订单和消息时会被引导进行手机号授权。登录后，个人中心展示头像、昵称、脱敏手机号、进行中订单和历史订单数量。

1
const maskedMobile = computed(() => {
2
  const mobile = String(auth.mobile || '')
3
  return /^(\d{3})\d{4}(\d{4})$/.test(mobile)
4
    ? mobile.replace(/^(\d{3})\d{4}(\d{4})$/, '$1****$2')
5
    : mobile || '未绑定手机号'
6
})

脱敏不应依赖模板截字符串，统一计算属性更容易复用和测试。

2. Auth Store 的职责#

store/modules/auth.js 保存 token、用户资料和头像临时地址，并暴露登录、退出、刷新资料、修改昵称和上传头像的方法。

1
const isLogin = computed(() => !!token.value)
2
const userId = computed(() => userInfo.value?.userId || null)
3
const nickname = computed(() => userInfo.value?.nickname || DEFAULT_USER_NICKNAME)

页面不直接操作本地存储。Store 在登录成功后同时更新响应式状态和持久化数据，退出时清理 token、资料与鉴权图片缓存。

3. 微信登录和手机号授权#

登录流程由 wxLoginFlow 与 phoneLoginFlow 封装。页面只负责获得授权事件并触发流程：

1
wx.login 获取临时 code
2
        ↓
3
手机号授权凭证
4
        ↓
5
后端换取 token 与用户资料
6
        ↓
7
保存认证状态并刷新头像

把平台 API 包装在 utils/wx 中，可以避免页面里到处出现回调式代码，也方便处理用户拒绝授权、会话失效等分支。

4. Token 失效后的刷新#

请求层遇到 401 时，若存在 token 和刷新器，会尝试刷新并重放原请求。多个请求同时 401 时共用一个 refreshPromise：

1
if (!refreshPromise) {
2
  refreshPromise = tokenRefresher()
3
    .finally(() => { refreshPromise = null })
4
}
5
return refreshPromise

这叫“单飞”控制。否则首页、消息和个人资料可能同时刷新三次 token，后端刚发的新 token 又被后一个响应覆盖。

刷新失败后统一清理认证并弹出登录提示，页面不需要各写一套 401 处理。

5. 头像为什么要鉴权下载#

头像接口不是公开静态地址，需要携带 token 获取临时文件。Store 使用 getAuthenticatedImage 下载，并维护缓存键 current-user-avatar。

上传新头像后，页面直接采用上传接口返回的最新资料，再强制刷新临时图。头像刷新使用 Promise 链串行执行：

1
avatarRefreshChain = avatarRefreshChain
2
  .catch(() => '')
3
  .then(() => getAuthenticatedImage(url, { cacheKey, force: true }))

这是为了避免 onShow 的旧请求晚于上传后的新请求返回，把新头像又覆盖回旧图。

6. 昵称和订单统计#

昵称通过小程序昵称输入能力采集，提交前执行长度和内容校验。保存成功后重新拉取 profile，以服务端结果为准。

个人中心的进行中/历史订单统计来自完整订单列表，再通过 isHistoryOrder 分类：

1
orderStats.value = orders.reduce((stats, order) => {
2
  if (isHistoryOrder(order)) stats.history += 1
3
  else stats.active += 1
4
  return stats
5
}, { active: 0, history: 0 })

下拉刷新时资料与统计通过 Promise.allSettled 并行加载，一项失败不影响另一项更新。

7. 本篇小结#

请求登录的时机#

登录弹窗不是应用一打开就出现。首页允许游客先了解服务，只有访问订单、地址、消息等需要身份的能力时才调用 requestPhoneLogin，并给出当前动作需要登录的原因。这样的授权更符合微信小程序的交互要求，也比无缘无故索要手机号更容易被理解。

退出登录清理什么#

退出时除了 token，还要清理用户资料、头像临时文件缓存、消息列表和可能残留的业务 Store。下次其他账号登录后，不能短暂看到上一位用户的头像或消息。公共配置和未提交的游客页面状态则不必一股脑删除。

个人资料接口失败时保留本地已有资料并提示刷新失败，不把头像和昵称突然清空。认证失败与普通网络失败要区别处理：前者引导重新登录，后者允许重试。

个人中心是用户身份的总入口，也最容易被并发和缓存捉弄。处理完登录、头像和资料刷新后，我终于理解：一张圆圆的头像背后，站着的不是一个 image 标签，而是一整支认证小队。

小程序开发日记②：订单列表、详情与支付状态

Sun, 09 Aug 2026 00:00:00 GMT

用户下单后最关心三件事：现在是什么状态、下一步要做什么、什么时候能送到。订单模块就围绕这三件事组织，而不是简单照搬管理端字段。

1. 列表状态分组#

订单页提供“全部、待支付、待调度、配送中、已完成”五个标签。接口返回的后台状态比标签更多，因此需要状态映射，而不能直接用标签文本请求。

1
const tabStatusMap = {
2
  0: null,
3
  1: ['UNPAID'],
4
  2: ['PENDING_AUDIT', 'WAIT_DISPATCH'],
5
  3: ['DELIVERING'],
6
  4: ['COMPLETED', 'CANCELED', 'REJECTED', 'DELIVERY_FAILED']
7
}

页面请求时增加版本号，用户快速切换标签后，只接收最后一次查询结果，避免慢请求把新标签的数据覆盖掉。

1
let queryVersion = 0
2

3
async function loadOrders() {
4
  const requestId = ++queryVersion
5
  const response = await OrderApi.getOrderList(params.value)
6
  if (requestId !== queryVersion) return
7
  orders.value = response.rows || []
8
}

2. 订单卡片是视图模型#

OrderStatusCard 统一处理状态颜色、右上角状态形状、价格、摘要和按钮。卡片不直接决定业务，只接收已经转换好的展示属性。

为了让背景图片覆盖整个盒子，图片层使用绝对定位，内容层单独抬高层级：

1
.order-card { position: relative; overflow: hidden; }
2
.order-card__background {
3
  position: absolute;
4
  inset: 0;
5
  width: 100%;
6
  height: 100%;
7
}
8
.order-card__content { position: relative; z-index: 1; }

右上角状态区域单独绘制与主题相近、但有区分度的色块，解决背景图边缘在圆角裁剪时露白的问题。

3. 详情页聚合数据#

pages/order/detail.vue 同时读取订单详情、进度记录和凭证图片。详情加载成功后，再根据状态构建页面头部、时间线和操作按钮。

1
async function loadDetail(showPageLoading = true) {
2
  if (!orderId.value || refreshing.value) return
3
  refreshing.value = true
4
  try {
5
    const [detailResult, progressResult] = await Promise.all([
6
      OrderApi.getOrderDetail(orderId.value),
7
      OrderApi.getOrderProgress(orderId.value)
8
    ])
9
    detail.value = detailResult.data || {}
10
    progressRecords.value = progressResult.rows || []
11
    await loadProofImages()
12
  } finally {
13
    refreshing.value = false
14
  }
15
}

展开收起

页面支持下拉刷新，并在可变状态下每 30 秒轻量刷新一次。离开页面必须清除计时器，避免隐藏页面继续请求。

4. 支付倒计时#

待支付订单根据创建或更新时间计算剩余时间：

1
const baseTime = Number.isNaN(updateTime) ? createTime : updateTime
2
const remain = PAYMENT_TIMEOUT - (Date.now() - baseTime)

倒计时归零后页面主动刷新详情，由服务端确认订单最终状态。前端不能擅自把订单改为取消，因为支付回调可能正在路上。

5. 支付与取消#

支付按钮设置 paying 防重复触发，调用支付接口后根据结果更新页面。取消操作先弹确认框，用户确认后调用 cancelOrder，成功再刷新详情。

1
点击取消
2
  ↓
3
确认风险与结果
4
  ↓
5
调用取消接口
6
  ↓
7
重新读取订单详情

对于已驳回订单，详情页提供“重新提交”，跳回对应类型表单并携带 orderId 与 resubmit=1。表单回显原数据，用户修改后走专门的重提接口。

6. 进度时间线#

时间线不是根据当前状态虚构节点，而是优先使用真实 process logs。只有后端暂未返回记录时才使用基础状态生成占位。审核、调度、起飞、签收都显示真实操作时间，用户才能知道订单究竟停在哪里。

7. 本篇小结#

前后台状态的解释差异#

管理端关心“待审核”和“待调度”的操作区别，用户端更关心“平台正在确认”和“等待安排配送”。页面没有修改原始枚举，而是通过视图函数提供用户文案。这样接口与排查日志仍使用统一状态，界面表达则更自然。

轮询的边界#

只有 UNPAID、PENDING_AUDIT、WAIT_DISPATCH、DELIVERING 等可变状态需要轮询。订单进入完成、取消、驳回等终态后停止计时器。页面隐藏时也停止，重新显示再立即拉取一次，避免小程序在后台持续耗电和请求。

详情中的价格、来源订单号、MMSI 和流程时间都通过统一格式化函数处理。缺失值显示 --，金额固定两位小数，订单号始终使用业务 orderNo。这些规则看起来零碎，但正是用户判断“是不是我的那张订单”的依据。

订单模块让我意识到，“状态”不是卡片右上角的四个字，而是接口、按钮、倒计时、时间线和跳转共同遵守的规则。只改颜色不改行为，就像给红灯刷成绿色，路还是会堵。

小程序开发日记①：快递与外卖下单流程

Sat, 08 Aug 2026 00:00:00 GMT

小程序最核心的动作是下单。项目支持快递和外卖两类配送，它们共享收货人、船舶和位置数据，但订单来源、货品字段、预计时间与图片凭证不同。

1. 两个页面，一套订单状态仓库#

页面分别位于：

pages/order/courier-form.vue：快递订单；
pages/order/takeaway-form.vue：外卖订单；
store/modules/order.js：两类订单的表单状态与 payload 构造；
store/modules/recipient.js：收货人与船舶地址。

没有强行把两张表单做成几十个条件分支的“万能页面”，而是共享数据模型和组件。页面保留各自业务表达，仓库负责复用。

2. 快递订单模型#

快递侧包含快递公司、快递单号、重量、体积和备注：

1
function buildCourierPayload(recipient) {
2
  return normalizeOrderPayload({
3
    ...(editingOrderId.value ? { orderId: editingOrderId.value } : {}),
4
    serviceType: 'EXPRESS',
5
    expressCompanyName: courierCompany.value,
6
    expressNo: courierNo.value,
7
    cargoWeightKg: packageWeight.value,
8
    cargoVolume: includeVolume.value ? Number(packageVolume.value) : null,
9
    cargoRemark: courierRemark.value,
10
    vesselName: recipient.shipName,
11
    mmsi: recipient.shipMmsi,
12
    receiverName: recipient.recipientName,
13
    receiverPhone: recipient.recipientPhone,
14
    regionId: recipient.regionId,
15
    shipLongitude: recipient.longitude,
16
    shipLatitude: recipient.latitude
17
  })
18
}

展开收起

重量必须大于 0，长宽高只有填写时才成组校验。可选字段不要用空字符串冒充有效数字，否则后端可能得到 0、NaN 或错误体积。

3. 外卖订单模型#

外卖侧包含平台、平台订单号、骑手电话、预计到达时间和备注：

1
function buildTakeawayPayload(recipient) {
2
  return normalizeOrderPayload({
3
    serviceType: 'TAKEOUT',
4
    sourcePlatformName: takeawayPlatform.value,
5
    sourceOrderNo: takeawayOrderNo.value,
6
    riderPhone: riderPhone.value,
7
    expectedArriveTime: buildTodayDateTime(arriveTime.value),
8
    cargoRemark: takeawayRemark.value,
9
    ...buildRecipientFields(recipient)
10
  })
11
}

预计时间选择器会限制最早可选时间，并把页面的时、分组合成后端需要的完整日期时间。不能只提交 13:40，否则服务端无法判断是哪一天。

4. 收货地址与服务范围#

下单页面优先读取默认地址，并把地址簿记录填入 recipientStore。提交前除了校验姓名、手机号、MMSI 和经纬度，还会检查坐标是否在服务区域内。

1
选择/读取默认地址
2
        ↓
3
校验收货信息完整性
4
        ↓
5
检查经纬度是否落在服务范围
6
        ↓
7
构造订单 payload

服务范围校验应该使用经纬度，而不是地址文本。两个名字相似的港区可能相距很远，文字无法替代空间关系。

5. 图片凭证上传#

订单截图和货品照片使用不同凭证类型：

1
await DeliveryApi.uploadProof(filePath, {
2
  orderId,
3
  proofType: DELIVERY_PROOF_TYPES.ORDER_PHOTO,
4
  sortNo: index + 1
5
})

提交顺序是先创建订单，拿到 orderId 后再上传图片。上传任务可以并行，但只有全部完成才提示成功：

1
const response = await OrderApi.createOrder(payload)
2
const orderId = response.data?.orderId || response.data
3
await uploadProofFiles(orderId)

6. 新增、修改与重新提交#

同一表单支持三种模式：

模式	判断条件	接口
新增	无 `editingOrderId`	create
修改	有订单 ID	update
驳回重提	`resubmit=1`	resubmit

编辑时通过 fillFromOrder 回显数据，并下载已有凭证为临时地址。仓库额外记录 existingOrderPhotoFiles 和 existingGoodsPhotoFiles，避免未变更的远程图片被重复上传。

1
const shouldUpload = (filePath, existingFiles) => {
2
  return isResubmitting.value || !existingFiles.includes(filePath)
3
}

删除已有图片时，则调用删除凭证接口并重新加载当前凭证集合，保持服务端和页面一致。

7. 防重复提交#

按钮的 loading 与 submitting 同时作为视觉反馈和逻辑锁：

1
if (submitting.value) return
2
submitting.value = true
3
try {
4
  // 创建或更新订单，再上传凭证
5
} finally {
6
  submitting.value = false
7
}

单靠按钮变灰不够，网络慢时用户可能连续触发事件，逻辑层仍需兜底。

8. 本篇小结#

下单失败如何保留现场#

接口失败后不能调用 reset()，用户选择的地址、订单号和图片都应保留。只有创建与凭证上传全部成功，才清理 Store 并跳转订单页。如果订单创建成功但图片上传失败，页面需要提示“订单已创建，凭证上传失败”，并允许进入编辑模式补传，不能再次创建一张重复订单。

页面返回时的状态边界#

从地址簿或地图选点返回属于下单流程的一部分，表单状态必须保留；从提交成功页重新发起下单，则需要干净的新表单。为此，Store 的清理动作由明确业务事件触发，而不是粗暴地写在每次 onUnload 中。

联调时我按“必填字段—服务范围—订单创建—凭证上传—成功跳转”逐段制造失败，确认每一步的按钮状态和用户输入都合理。这比只测一次顺利下单更能暴露流程问题。

下单流程表面是填表，实际串起了地址、空间校验、订单状态和图片凭证。两个页面既不能复制粘贴到失控，也不能抽象成谁都看不懂的超级表单。最后我找到的平衡是：业务页面各说各话，共用仓库在背后默契配合。

管理端开发日记⑦：报表快照与运营指标

Fri, 07 Aug 2026 00:00:00 GMT

实时大屏强调“此刻”，报表快照强调“某个时间段发生了什么”。日报、周报和月报切换后，核心指标、趋势、来源结构和超时数据都必须同时改变。

1. 页面指标#

src/views/manage/report-snapshot/index.vue 展示订单总量、完成率、平均配送时长、超时数、异常数和取消数，并用三张图展示平台占比、趋势和超时/价格比较。

区域	图表	问题
平台结构	环形图	订单主要来自哪里
订单趋势	折线图	当前周期如何变化
超时与价格	柱状图	哪些日期或类别值得关注

2. 周期切换#

1
const activePeriod = ref('day')
2

3
watch(activePeriod, () => loadReport())

不同周期可以对应不同接口，也可以使用同一接口的 period 参数。页面不直接绑定原始响应，而是先通过 applyReportData 转成统一模型。

1
function applyReportData(data = {}) {
2
  summary.value = normalizeSummary(data.summary)
3
  compare.value = normalizeCompare(data.compare)
4
  platformData.value = normalizePlatform(data.platform)
5
  trendData.value = normalizeTrend(data.trend)
6
  nextTick(renderCharts)
7
}

统一模型让图表配置不必判断“日报字段叫 todayTotal、月报字段叫 monthTotal”。接口差异在适配层结束，组件只消费稳定结构。

3. 防止请求竞态#

快速点击“日、周、月”会产生多个并发请求。较早发出的请求可能最后才返回，从而覆盖最新选择。页面使用版本号识别过期响应：

1
let requestVersion = 0
2

3
async function loadReport() {
4
  const currentVersion = ++requestVersion
5
  const response = await fetchReport(activePeriod.value)
6
  if (currentVersion !== requestVersion) return
7
  applyReportData(response.data)
8
}

这段代码很短，却能解决非常隐蔽的“切换后偶尔显示错周期”问题。

4. 图表实例集中管理#

1
const charts = []
2

3
function initChart(el, option) {
4
  const chart = echarts.init(el, null, { renderer: 'canvas' })
5
  chart.setOption(option)
6
  charts.push(chart)
7
  return chart
8
}
9

10
function resizeCharts() {
11
  charts.forEach(chart => chart.resize())
12
}

组件卸载时遍历 dispose()，窗口改变时统一 resize()。集中管理避免每张图各自注册窗口事件。

5. 图表配置中的可读性#

平台占比使用环形图并在中心显示总量；趋势图使用平滑折线但保留数据点；柱状图使用渐变色突出超时或价格差异：

1
itemStyle: {
2
  color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
3
    { offset: 0, color: '#4b8cff' },
4
    { offset: 1, color: '#1769e8' }
5
  ]),
6
  borderRadius: [6, 6, 0, 0]
7
}

图表配置不是越复杂越好。tooltip、单位、空数据和小数精度比炫酷阴影更直接影响理解。

6. 同比/环比的表达#

比较值除了数字，还要表达方向和好坏。订单量增加通常是正向，异常率增加却是负向。因此不能简单地把“上升”都涂成绿色，而应根据指标语义决定颜色。

1
function trendTone(value, lowerIsBetter = false) {
2
  const rising = Number(value) > 0
3
  const positive = lowerIsBetter ? !rising : rising
4
  return positive ? 'positive' : 'negative'
5
}

7. 接口失败与演示数据#

开发阶段页面保留可控的 mock 回退，正式环境则展示明确空状态。回退数据只能用于布局联调，不能伪装成真实运营结果。报表页面的可信度比“永远有图”更重要。

8. 本篇小结#

快照和实时查询的区别#

如果报表数据来自已经生成的快照，页面应展示快照生成时间，不能把它标成“实时”。快照适合固定口径和快速打开，实时聚合适合临时查询；两者可以同时存在，但必须让用户知道自己看到的是哪一种。

指标校验#

联调时我会做几组关系校验：完成数不能大于总订单数；完成、取消、异常等分类之和与总量的差异要能解释；平台占比的分母一致；趋势点日期不重复且按时间递增。前端不会替后端修正业务数据，但可以在开发环境输出警告，尽早发现字段映射错位。

导出报表时同样携带当前周期与筛选参数，文件名包含周期和生成时间。页面图表、指标卡和导出文件共享同一查询上下文，才能称为同一份报表。

报表快照的难点不在画三张图，而在周期、口径、竞态和生命周期。把这些基础工作做好以后，图表才是一张报告；否则它只是一组很会变颜色的 canvas。

管理端开发日记⑥：数据大屏与首页数据分析

Thu, 06 Aug 2026 00:00:00 GMT

管理端首页回答“今天发生了什么”，数据大屏回答“整体运营得怎么样”。两者都展示数据，却面向不同观看距离、使用频率和决策场景。

1. 首页指标卡#

首页 src/views/index.vue 展示今日订单、待审核、待调度、飞行中、已完成和异常订单六项指标。指标不只是一排数字，它们对应每天最常见的管理动作。

1
const metrics = computed(() => [
2
  { key: 'todayTotal', label: '今日订单', value: stats.value.todayTotal },
3
  { key: 'pendingAudit', label: '待审核', value: stats.value.pendingAudit },
4
  { key: 'waitDispatch', label: '待调度', value: stats.value.waitDispatch },
5
  { key: 'flying', label: '飞行中', value: stats.value.flying },
6
  { key: 'completed', label: '已完成', value: stats.value.completed },
7
  { key: 'exception', label: '异常订单', value: stats.value.exception }
8
])

卡片点击后可以携带状态跳转到对应列表，让“发现问题”和“处理问题”之间少一次搜索。

2. 首页图表#

首页使用饼图展示状态分布，用折线图展示订单趋势。加载接口后先规范化数值，再更新已有实例：

1
function upsertChart(el, current, option) {
2
  const chart = current || echarts.init(el)
3
  chart.setOption(option, true)
4
  return chart
5
}

复用实例比每次刷新都 echarts.init 更安全，能减少重复 canvas 和事件监听。

3. 固定设计稿如何适配屏幕#

运营大屏通常按固定尺寸设计，但实际显示器比例并不完全相同。src/views/data-screen/index.vue 使用 ResizeObserver 监听容器，并计算统一缩放：

1
const scale = Math.min(
2
  containerWidth / DESIGN_WIDTH,
3
  containerHeight / DESIGN_HEIGHT
4
)

外层容器负责居中，内部画布保持设计尺寸并通过 transform: scale(...) 缩放。这样各面板的相对位置和图表比例不被单独拉伸。

4. 运营驾驶舱的内容层次#

运营大屏主要组合：订单总览、完成率仪表盘、订单趋势、平台来源分布、异常概览和航线场景。信息按“总量—趋势—结构—异常—空间”排列。

1
运营总览
2
 ├─ 总量：订单数、完成数、异常数
3
 ├─ 效率：完成率、平均时长
4
 ├─ 趋势：分时/分日订单变化
5
 ├─ 结构：平台与服务类型占比
6
 └─ 场景：航线与飞行态势

大屏不是把所有接口字段都放上去，而是选择站在远处也能迅速判断的指标。字体、颜色和动效都服务于“几秒内读懂”。

5. 用户服务大屏#

用户服务页使用折线图呈现投诉趋势，用仪表盘展示满意度。它与运营驾驶舱共用大屏外壳和缩放策略，但指标口径独立。这样既保持统一视觉，又不会把订单效率和用户评价混成一套概念。

6. 初始动画与页面激活#

大屏可能被路由缓存。首次进入、从其他页面切回和窗口变化都会影响图表尺寸，所以页面在激活后重新执行 resize，必要时重播强调动画：

1
function replayHighlight(chart, dataIndex = 0) {
2
  chart.dispatchAction({ type: 'downplay', seriesIndex: 0 })
3
  chart.dispatchAction({ type: 'highlight', seriesIndex: 0, dataIndex })
4
  chart.dispatchAction({ type: 'showTip', seriesIndex: 0, dataIndex })
5
}

动画只用于引导视线，不能不停闪烁抢走注意力。

7. 数据口径与空数据#

所有展示值先转换为数字，缺失数据用 0 或 --，百分比统一限定范围。趋势数组为空时显示空状态，而不是让坐标轴报错。大屏最怕“画得很满，数字却说不清从哪里来”，因此每个指标都应能追溯到接口字段与统计时间范围。

8. 本篇小结#

从接口响应到大屏指标#

大屏不直接使用订单明细做所有统计。高频访问的总览指标由后端聚合接口返回，前端只负责格式化；少量临时指标才在已有结果上计算。让浏览器下载全部订单再统计，不仅慢，还可能因权限和分页得到错误口径。

数据刷新时保留旧图，成功后一次性替换模型，避免每个指标先后跳动。若请求失败，则显示最后更新时间和失败提示，而不是把旧数据悄悄当成当前数据。

大屏的性能边界#

固定画布缩放、ECharts 动画和地图场景可能同时运行。页面激活时启动，失活时暂停轮播和动画；ResizeObserver 做节流，避免浏览器改变尺寸时连续触发大量 resize。装饰性动画也优先使用 transform 与 opacity，减少布局重排。

首页像值班表，大屏像指挥舱。前者讲究快，后者讲究全局感。把两者的职责分开以后，图表不再只是漂亮背景，而是真的能提醒我：今天到底是订单多，还是问题多。

管理端开发日记⑤：地图航线与无人机定位

Wed, 05 Aug 2026 00:00:00 GMT

配送订单进入飞行阶段后，纯文字状态已经不够。调度人员需要在地图上同时看到接驳点、船舶位置、规划航线和无人机当前位置。本篇记录这套“让数据真正飞起来”的过程。

1. 地图数据来自哪里#

订单详情页会组合订单坐标、接驳点配置、航线航点和飞行任务：

地图对象	主要来源
起点	接驳点或机巢配置
终点	订单中的船舶经纬度
航线	航线任务返回的点集合
无人机	飞行任务当前进度或实时位置

地图组件只负责画，业务层先把不同接口的字段归一成 { latitude, longitude }，避免渲染函数同时认识 lat、lng、waylineLatitude 等多套命名。

1
function normalizePoint(point = {}) {
2
  const latitude = Number(point.latitude ?? point.lat ?? point.y)
3
  const longitude = Number(point.longitude ?? point.lng ?? point.x)
4
  return Number.isFinite(latitude) && Number.isFinite(longitude)
5
    ? { latitude, longitude }
6
    : null
7
}

2. 初始化顺序#

地图初始化依赖容器尺寸，航线又依赖详情数据，因此流程必须有顺序：

1
loadDetail
2
   ├─ 读取订单和飞行任务
3
   ├─ 加载天地图脚本
4
   └─ nextTick
5
         ├─ initMap
6
         ├─ renderBaseRoute
7
         └─ startDroneAnimation

地图脚本只加载一次，实例也尽量复用。如果标签页切换回来重复创建地图，会出现覆盖物叠加、监听器重复和内存增长。

3. 航线绘制与端点标记#

有效航点不少于两个时绘制折线，同时把第一个点和最后一个点标记为起点、终点：

1
function renderWayline(points) {
2
  const validPoints = points.map(normalizePoint).filter(Boolean)
3
  if (validPoints.length < 2) return renderBaseRoute()
4

5
  routePolyline = new T.Polyline(
6
    validPoints.map(p => new T.LngLat(p.longitude, p.latitude)),
7
    { color: '#1769e8', weight: 6, opacity: 0.9 }
8
  )
9
  map.addOverLay(routePolyline)
10
  addEndpointMarker(validPoints[0], 'start')
11
  addEndpointMarker(validPoints.at(-1), 'end')
12
}

当后端暂未返回航线时，页面退化为起点到终点的基础路线，而不是直接留下一块白地图。降级展示可以让调度人员至少确认配送方向。

4. 无人机位置不是 CSS 位移#

无人机图标必须是地图覆盖物，它的位置由经纬度决定。若把一个普通 div 叠在地图上，再用像素计算移动，缩放和拖动地图后就会发生悬浮偏移。

1
droneMarker.setLngLat(
2
  new T.LngLat(point.longitude, point.latitude)
3
)

图标锚点同样重要。无人机图片较大时，应让坐标落在机身中心或吊舱位置，而不是图片左上角。地图缩放不会改变地理坐标，但错误锚点会让视觉误差更加明显。

5. 按线段长度计算动画#

如果每一段都用相同时间，短线段会慢、长线段会突然加速。页面先计算总距离，再按距离分配动画时间：

1
const segmentDuration = totalDuration * segmentDistance / totalDistance
2

3
function interpolate(start, end, progress) {
4
  return {
5
    longitude: start.longitude + (end.longitude - start.longitude) * progress,
6
    latitude: start.latitude + (end.latitude - start.latitude) * progress
7
  }
8
}

动画帧根据飞行开始时间和预计时长计算整体进度，再找到当前所在的线段。这使刷新页面后无人机不会从起点重新飞，而是恢复到合理位置。

6. 生命周期清理#

地图页面离开时必须停止动画、移除覆盖物和事件：

1
function stopDroneAnimation() {
2
  if (animationFrameId) cancelAnimationFrame(animationFrameId)
3
  animationFrameId = 0
4
}
5

6
onBeforeUnmount(() => {
7
  stopDroneAnimation()
8
  map?.clearOverLays?.()
9
  map = null
10
})

不清理的典型表现是：回到列表后 CPU 仍然占用，再次进入详情出现两架无人机同时移动。

7. 本篇小结#

实时位置与演示动画要分开#

地图若能获取无人机实时遥测，应直接使用最新坐标并标注更新时间。按起飞时间推算的动画只能作为缺少实时数据时的视觉补充，不能让调度人员误以为那是精确位置。页面数据模型因此保留 positionSource 和 lastUpdatedAt 的概念，便于在界面上解释来源。

航线刷新#

任务变化时先移除旧 polyline、marker 和动画，再渲染新航线。只在原地图上不断 addOverLay 会让旧线路残留。适配视野也不是每一帧都执行，而是在首次加载、航线切换或用户主动点击“查看全程”时执行，否则地图会不停把用户拖回自动视角。

地图相关问题最终形成了一套排查顺序：先看坐标字段，再看经纬度顺序和坐标系，然后检查覆盖物类型与锚点，最后才调整图标尺寸。这个顺序比从 CSS 开始碰运气稳定得多。

地图功能最考验“坐标世界”和“页面世界”的边界。航点属于地理坐标，图标属于覆盖物，不能拿普通 CSS 去假装地图引擎。修好以后，无人机终于老老实实贴着航线飞，不再像一张贴在显示器上的贴纸。

管理端开发日记④：三种异常处置流程的实现

Tue, 04 Aug 2026 00:00:00 GMT

异常工单真正难的地方，从来不是点一下“处理”。取消、重派和补发看起来都是解决问题，背后修改的数据却完全不同：有的终止原任务，有的保留原订单并生成新链路，有的还涉及退款。

1. 统一入口，不强行统一业务#

三种流程共用 ExceptionProcessPage 和 useExceptionProcess.js，但不会为了复用而把所有字段揉成一团。

1
const PROCESS_TYPES = {
2
  CANCEL: '取消退款',
3
  REDISPATCH: '重新派送',
4
  RESHIPMENT: '补发订单'
5
}

公用部分包括异常概览、原订单信息、凭证、处理日志和底部操作区；差异部分由 processType 决定请求、表单和提交动作。

2. 页面阶段：登记与跟踪#

处置页并非只有“未处理/已处理”。重派和补发在创建派生订单后还需要继续跟踪，因此定义两个页面阶段：

1
const stage = computed(() => {
2
  return ticket.value?.resultOrderId ? 'tracking' : 'registration'
3
})

registration：确认方案、填写原因、创建后续任务；
tracking：展示新订单、新飞行任务和合并后的流程日志。

这个阶段模型让刷新页面后仍能根据服务端数据还原视图，不需要依赖浏览器内存中的“刚刚提交成功”。

3. 取消退款流程#

取消流程需要先判断当前订单和飞行任务是否允许取消。如果任务仍在 WAIT_TAKEOFF，先停止任务，再调用取消退款接口，最后更新异常工单状态和用户消息。

1
读取原订单与退款信息
2
        ↓
3
校验订单是否仍可取消
4
        ↓
5
取消待起飞任务（如存在）
6
        ↓
7
提交取消/退款
8
        ↓
9
更新工单与通知

这一顺序不能随意交换。如果先把工单关闭，再取消飞行任务失败，就会出现“页面显示处理完毕，但无人机任务仍在”的数据裂缝。

4. 重新派送流程#

重派适用于原货物仍可继续配送，但需要重新安排飞行任务的情况。它通过专用接口建立新的调度关系，同时保留原订单作为问题来源。

重派编号会带有可辨识前缀和序号：

1
function buildRedispatchNo(sourceOrderNo, sequence) {
2
  return `RP${sourceOrderNo}-${String(sequence).padStart(2, '0')}`
3
}

这样客服从编号就能判断它不是独立的新订单，而是某张订单的再次派送。

5. 补发流程与子订单#

补发意味着需要创建一张派生订单。新订单复制必要的收货、货品和服务信息，但必须清空自身主键、当前任务等运行态字段：

1
function createDerivedOrder(original, sequence) {
2
  return {
3
    ...original,
4
    orderId: undefined,
5
    currentTaskId: undefined,
6
    parentOrderId: original.orderId,
7
    orderNo: `${original.orderNo}-B${sequence}`,
8
    orderStatus: 'WAIT_DISPATCH',
9
    deliveryFee: 0
10
  }
11
}

这里最容易出错的是“复制得太完整”。如果把原订单 ID 或已完成任务一起提交，新订单就会继承不属于自己的状态。派生订单应复制业务事实，不复制数据库身份和运行过程。

补发完成后，还要分别写入原订单和子订单的流程日志，并把子订单 ID 写回异常工单的 resultOrderId。这三个动作建立了可追踪的关系链：

1
异常工单 ── resultOrderId ──> 补发子订单
2
    │                              │
3
    └── orderId ──> 原订单 <── parentOrderId

6. 合并流程日志#

进入跟踪阶段后，页面同时加载原订单和派生订单日志。合并时按 processId 去重，再按操作时间排序：

1
const logMap = new Map()
2

3
originalLogs.concat(childLogs).forEach(log => {
4
  logMap.set(String(log.processId), log)
5
})
6

7
const mergedLogs = [...logMap.values()].sort((a, b) => {
8
  return new Date(a.operateTime) - new Date(b.operateTime)
9
})

用户看到的是一条连续故事，而不是两张互不相干的日志表。

7. 异步加载的容错#

处置页会并行读取订单、凭证、日志、退款、子订单和飞行任务。非核心数据使用 Promise.allSettled，关键动作则必须串行并在失败时中止。简单说就是：展示数据可以“尽量多拿”，写业务数据必须“每一步都算数”。

8. 本篇小结#

一致性与恢复能力#

三种流程都包含多个写动作，理想情况下应由后端事务或专用业务接口保证一致性。前端不能通过连续调用几个 CRUD 就假装拥有事务能力。若接口暂时拆分，页面至少要做到：前一步失败不执行后一步、错误信息明确、重新进入页面能根据工单与子订单数据恢复阶段。

1
页面内存不是流程凭证
2
工单状态 + resultOrderId + 流程日志才是恢复依据

重复点击“补发”时，后端需要检查是否已有 resultOrderId；重复取消时检查订单和退款状态；重派接口则要避免生成两条有效任务。前端的 submitting 只拦住当前设备上的连点，真正的幂等仍在服务端。

为什么保留原订单#

重派和补发都不直接覆写原订单，因为原订单包含用户最初提交的事实、审核意见和失败过程。派生对象记录后续补救，父子关系负责追溯。若直接把原订单从“失败”改成“待调度”，历史看起来会像失败从未发生，报表口径也会被悄悄改写。

三种异常流程让我真正感受到状态机不是画在文档里的箭头，而是数据之间不能走错的路。取消要收尾，重派要续跑，补发要另起一条支线。把关系理顺以后，复杂流程就不再像一锅面条——至少能看清哪根是自己的。

管理端开发日记③：异常列表、统计与筛选

Mon, 03 Aug 2026 00:00:00 GMT

正常订单沿着固定状态向前走，异常订单则会突然岔路。异常管理页的目标不是简单罗列报错，而是帮助客服判断优先级、找到关联订单，并把工单送入正确的处置流程。

1. 组件拆分#

入口文件 src/views/manage/exception-ticket/index.vue 主要负责组合：

组件	职责
`ExceptionListFilters`	关键词、类型、来源、状态和级别筛选
`TicketStatistics`	待处理、处理中、今日关闭、紧急工单统计
`ExceptionTicketTable`	工单展示与操作入口
详情/关闭弹窗	查看证据与填写处理结果
`ExceptionProcessPage`	取消、重派、补发的专用处置页

页面自身只管理“当前显示列表还是处置流程”，数据逻辑放进 useExceptionTicketList.js。这种拆分比在一个 .vue 文件里同时维护表格、弹窗和十几个接口清晰得多。

2. 查询条件与业务关键词#

1
const query = reactive({
2
  pageNum: 1,
3
  pageSize: 16,
4
  keyword: '',
5
  exceptionType: '',
6
  exceptionSource: '',
7
  processStatus: '',
8
  severityLevel: '',
9
  orderByColumn: 'createTime',
10
  isAsc: 'desc'
11
})

关键词不仅匹配异常编号，还要考虑订单号、手机号和 MMSI。服务端未一次性返回全部关联字段时，页面先获取工单，再补全订单资料。

3. 为什么需要订单信息补全#

异常表保存的是 orderId，但管理人员真正会搜索和核对的是订单号、船名、收货人和 MMSI。组合式函数通过订单详情接口补齐：

1
async function enrichOrderInfo(rows) {
2
  const results = await Promise.allSettled(
3
    rows.map(item => getDeliveryOrder(item.orderId))
4
  )
5

6
  return rows.map((item, index) => ({
7
    ...item,
8
    orderInfo: results[index].status === 'fulfilled'
9
      ? results[index].value.data
10
      : null
11
  }))
12
}

使用 Promise.allSettled 可以让某一张历史订单读取失败时，其余工单继续显示。补全后，页面再执行本地关键词匹配：

1
const haystack = [
2
  item.exceptionOrderNo,
3
  item.orderInfo?.orderNo,
4
  item.orderInfo?.receiverPhone,
5
  item.orderInfo?.mmsi
6
].join(' ').toLowerCase()

这也说明了为什么界面不能直接展示 orderId：它是关联键，不是业务人员交流时使用的编号。

4. 统计卡片与列表必须使用同一口径#

顶部统计包括：

待处理：尚未进入处置流程；
处理中：已经登记处置但未完成；
今日关闭：当天完成闭环；
紧急工单：严重级别较高且尚未关闭。

统计可以由后端专用接口返回，也可以在当前数据集上计算，但必须明确口径。分页列表的 16 条数据不能直接被误当成全部工单，否则统计会随翻页变化。

1
const statistics = computed(() => ({
2
  pending: allRows.value.filter(isPending).length,
3
  processing: allRows.value.filter(isProcessing).length,
4
  closedToday: allRows.value.filter(isClosedToday).length,
5
  urgent: allRows.value.filter(isUrgentAndOpen).length
6
}))

5. 路由参数驱动列表和处置页#

异常页面支持通过 exceptionId 与 processType 打开处置流程。有效类型只有：

1
const validProcessTypes = ['CANCEL', 'REDISPATCH', 'RESHIPMENT']

当路由参数合法时显示 ExceptionProcessPage，否则回到列表。这样列表和流程仍处在管理端布局下，也能通过刷新或复制链接恢复当前工单。

6. 枚举集中管理#

异常类型、来源、处理状态、严重程度和处置方式都放在 options.js 中。每个枚举同时提供值、文本和颜色，筛选器与表格共用同一份配置。

1
export const severityOptions = [
2
  { value: 'NORMAL', label: '普通', type: 'info' },
3
  { value: 'URGENT', label: '紧急', type: 'danger' }
4
]

集中枚举能防止同一个状态在筛选器叫“待处理”，在表格又叫“未处理”。文字统一看似小事，却直接影响客服是否理解流程。

7. 本篇小结#

前端补全与 N+1 查询的取舍#

逐条读取订单详情能够快速完成联调，但当一页有 16 条工单时，最坏会多出 16 个请求。当前实现通过 ID 去重、并发请求和失败容错控制影响；更长期的方案是让异常列表接口直接联表返回 orderNo、船名和联系方式，或者提供批量订单摘要接口。

1
短期：异常 rows → 去重 orderId → 并发详情 → 前端合并
2
长期：异常列表 DTO 直接携带 OrderSummary

页面还需要在筛选条件变化时重置页码和已选行，关闭详情弹窗后根据是否发生写操作决定是否刷新列表。筛选项多并不意味着每次输入都立刻请求，关键词可以在回车或点击查询时提交，枚举变化再即时刷新，减少无意义的往返。

这些细节最终都服务于同一目标：工单数量很多时，用户依然能稳定地找到那一张真正需要先处理的异常。

异常列表的核心是把“技术关联”翻译成“业务可读信息”，再按优先级送入处置链路。页面最终像一个交通指挥台：红灯不能只亮着，还得告诉人哪条路堵了、该往哪里绕。

管理端开发日记②：订单详情、流程与数据回显

Sun, 02 Aug 2026 00:00:00 GMT

列表解决“找到订单”，详情页解决“理解订单”。一个订单详情并不是一张表，而是订单资料、业务凭证、审核记录、状态流转和飞行任务的聚合视图。

1. 页面结构#

src/views/manage/delivery-order/detail.vue 采用左侧地图、右侧信息区的布局。右侧按内容拆分为基础信息、图片凭证、流程记录和操作区。

数据	来源	用途
订单详情	订单详情接口	基础字段和当前状态
订单凭证	凭证接口	订单图、货品图、签收图
历史版本	订单历史接口	驳回再提交前后的变化
流程日志	progress 接口	审核、调度、起飞、完成节点
飞行任务	飞行任务接口	航线、起降点和飞行状态

2. 多数据源回显#

详情页不能把所有数据硬塞进一个超大接口。订单与飞行任务的更新频率不同，图片也需要鉴权下载，因此页面分别请求，再汇总成视图模型。

1
async function loadDetail() {
2
  loading.value = true
3
  try {
4
    const [orderResult, proofResult, historyResult, logResult] =
5
      await Promise.allSettled([
6
        getDeliveryOrder(orderId.value),
7
        listDeliveryProof({ orderId: orderId.value }),
8
        listDeliveryOrderHistory({ orderId: orderId.value }),
9
        getDeliveryOrderProcessLogs(orderId.value)
10
      ])
11

12
    detail.value = valueOf(orderResult, {})
13
    proofList.value = rowsOf(proofResult)
14
    orderHistoryList.value = rowsOf(historyResult)
15
    processLogs.value = rowsOf(logResult)
16
    await loadWayline()
17
  } finally {
18
    loading.value = false
19
  }
20
}

展开收起

这里使用 Promise.allSettled 而不是 Promise.all，因为某一组非核心数据失败时，不应让整个详情页变成空白。例如签收图暂时读取失败，订单基本资料与流程日志仍然可以展示。

3. 图片凭证按业务类型分组#

凭证并不是普通附件，它带有明确语义：

1
const proofGroups = {
2
  ORDER_PHOTO: '订单截图',
3
  GOODS_PHOTO: '货品照片',
4
  SIGN_PHOTO: '签收凭证'
5
}

页面通过 AuthenticatedImage 获取受保护图片，而不是直接拼接服务器路径。这样既携带登录凭证，又可以统一处理加载失败、临时地址和缓存。

图片分组后，审核员可以快速判断“订单来源是否可信”“货品是否满足飞行条件”；订单完成后又能独立查看签收凭证，不会把所有图片混成一排。

4. 流程日志比当前状态更有解释力#

当前状态只能说明现在在哪里，流程日志才能解释为什么走到这里。页面将日志按时间排序并构造成时间线：

1
const sortedLogs = computed(() => [...processLogs.value].sort((a, b) => {
2
  return new Date(a.operateTime || a.createTime) -
3
    new Date(b.operateTime || b.createTime)
4
}))

每个节点显示操作名称、操作人、时间和备注。对于被驳回后重新提交的订单，还会从历史记录中读取 rejectReason、rejectExplain，让新版本和旧版本之间的关系可追溯。

5. 状态驱动底部操作区#

详情页不允许用户随意触发任何接口，而是由订单状态确定按钮：

当前状态	可执行动作
`PENDING_AUDIT`	审核通过、驳回
`WAIT_DISPATCH`	取消订单、开始飞行
`DELIVERING`	标记配送成功、配送失败
终态	只读查看

1
<template v-if="detail.orderStatus === 'PENDING_AUDIT'">
2
  <el-button @click="rejectOrder">驳回</el-button>
3
  <el-button type="primary" @click="approveOrder">审核通过</el-button>
4
</template>

每次操作成功后重新执行 loadDetail()，而不是在前端手工猜测新状态。服务端才是状态机的最终裁判，重新拉取可以同步流程日志、任务编号和更新时间。

6. 数据回显中的空值和异步顺序#

详情数据返回前，模板中的 detail.orderStatus、坐标和图片列表都可能为空。页面默认使用空对象和空数组，并用 -- 处理缺失字段。地图必须在容器完成渲染后初始化，航线又依赖订单坐标和任务数据，因此加载顺序大致为：

1
读取订单与关联数据
2
        ↓
3
等待 DOM 完成渲染
4
        ↓
5
初始化地图实例
6
        ↓
7
解析航点并绘制航线
8
        ↓
9
放置起点、终点和无人机

这类顺序问题不会总是报错，却会表现为“偶尔没有线”“切换页面后地图空白”，所以比普通表单更需要明确生命周期。

7. 本篇小结#

操作幂等与二次确认#

详情页的写操作都增加提交锁，高风险动作增加确认弹窗。前端提交锁用于避免双击，后端仍需依据当前状态做幂等校验。例如两名管理员同时审核同一订单，后提交的一方应该收到“状态已变化”，而不是重复生成流程日志。

1
if (submitting.value) return
2
submitting.value = true
3
try {
4
  await approveDeliveryOrder(detail.value.orderId)
5
  await loadDetail()
6
} finally {
7
  submitting.value = false
8
}

详情页的降级顺序#

我把信息分为三个等级：订单基础信息是页面成立的前提；流程日志和任务信息失败时显示局部错误；图片加载失败只影响对应缩略图。这样网络不稳定时，页面不是“全有或全无”。

另外，切换订单 ID 时先停止旧的地图动画、清空凭证临时 URL，再加载新数据。否则组件复用可能让上一张订单的无人机和下一张订单的资料短暂出现在同一屏，堪称跨订单串门。

订单详情是典型的聚合页面：接口多、状态多、展示层次也多。把数据源分开请求、在视图层重新编排，比追求一个万能接口更容易维护。我写到最后的感受是，详情页像侦探桌上的线索板——每根线都要接对，故事才讲得通。

管理端开发日记①：订单列表与状态筛选

Sat, 01 Aug 2026 00:00:00 GMT

订单列表看起来只是“搜索框加表格”，但它其实是管理端最重要的业务入口：审核、调度、配送、完成和异常都从这里分流。今天就把这个不起眼、但每天都要被点开很多次的页面拆开看看。

1. 页面承担的职责#

订单列表主要位于 src/views/manage/delivery-order/index.vue，接口封装位于 src/api/manage/deliveryOrder.js。页面没有把所有操作都塞进弹窗，而是负责四件事：

按订单号、船名和状态筛选订单；
以服务类型和状态标签快速呈现业务差异；
根据当前状态给出合法操作；
把复杂业务交给订单详情页继续处理。

这种分工很重要。列表页适合“找数据”和“做决策”，详情页才适合展示凭证、轨迹、流程日志等重信息。

2. 查询模型要和分页模型放在一起#

页面使用统一的查询对象保存筛选条件和分页信息：

1
const queryParams = reactive({
2
  pageNum: 1,
3
  pageSize: 10,
4
  orderNo: undefined,
5
  vesselName: undefined,
6
  orderStatus: undefined,
7
  orderByColumn: 'createTime',
8
  isAsc: 'desc'
9
})

查询按钮并不是直接重新请求，而是先回到第一页：

1
function handleQuery() {
2
  queryParams.pageNum = 1
3
  getList()
4
}
5

6
async function getList() {
7
  loading.value = true
8
  try {
9
    const response = await listDeliveryOrder(queryParams)
10
    orderList.value = response.rows || []
11
    total.value = Number(response.total || 0)
12
  } finally {
13
    loading.value = false
14
  }
15
}

展开收起

如果用户原本停在第 8 页，再加一个筛选条件后仍请求第 8 页，很容易得到“没有数据”的假象。把筛选条件与分页状态放在同一个模型中，可以明确每次请求到底携带了什么。

3. 状态不是文字，而是业务规则#

当前订单状态包括：

状态值	页面含义	主要操作
`UNPAID`	待支付	查看详情
`PENDING_AUDIT`	待审核	审核、驳回
`WAIT_DISPATCH`	待调度	取消、开始飞行
`DELIVERING`	配送中	完成配送、配送失败
`COMPLETED`	已完成	查看详情
`DELIVERY_FAILED`	配送失败	查看异常和流程
`CANCELED`	已取消	查看详情
`REJECTED`	已驳回	查看驳回原因

我最初容易把状态处理写成模板里的大量 v-if。后来将“标签颜色”和“允许操作”分别抽成映射，让模板只负责渲染：

1
const statusMeta = {
2
  PENDING_AUDIT: { label: '待审核', type: 'warning' },
3
  WAIT_DISPATCH: { label: '待调度', type: 'primary' },
4
  DELIVERING: { label: '配送中', type: 'success' },
5
  COMPLETED: { label: '已完成', type: 'info' }
6
}
7

8
const rowActions = {
9
  PENDING_AUDIT: ['detail', 'audit'],
10
  WAIT_DISPATCH: ['detail', 'startFlight'],
11
  DELIVERING: ['detail', 'deliveryResult'],
12
  COMPLETED: ['detail']
13
}

状态表的价值不只是少写几行代码。新增状态时，开发者可以从一个入口检查“显示什么、允许做什么”，不必在整张模板里寻找条件分支。

4. 表格字段体现业务优先级#

订单数据很多，但列表只展示快速判断所需的信息：订单号、来源单号或快递单号、服务类型、来源平台、船名、收货人、MMSI、手机号、状态和创建时间。

订单号设置为可点击文本，点击后进入详情。服务类型则把 EXPRESS、TAKEOUT 转成“快递配送”和“外卖配送”。类似转换不应散落在每个单元格中，可以统一封装：

1
function serviceTypeText(value) {
2
  return value === 'EXPRESS' ? '快递配送'
3
    : value === 'TAKEOUT' ? '外卖配送'
4
      : '-'
5
}

列表中不直接展示数据库自增 ID。自增 ID 适合前后端定位记录，订单号才适合客服、调度员和用户沟通，这也是业务标识与技术标识必须区分的地方。

5. 操作入口为什么跳转详情页#

审核需要查看订单照片，起飞需要核对航线和无人机，配送完成需要上传或查看签收凭证。因此列表中的“审核”“开始飞行”最终都进入同一个详情页，只是详情页会根据状态展示不同按钮。

1
function openDetail(row) {
2
  router.push(`/manage/delivery-order/detail/${row.orderId}`)
3
}

详情路由挂在管理端的 Layout 下面，并通过 activeMenu 保持订单菜单高亮。这样页面跳转后，顶部标题栏和侧边导航不会消失，用户也不会突然从管理系统的框架中“掉出去”。

6. 导出应复用当前筛选条件#

导出不是导出全部数据，而是导出用户当前看到的业务范围：

1
function handleExport() {
2
  proxy.download(
3
    '/manage/admin/delivery-order/export',
4
    { ...queryParams },
5
    `订单_${Date.now()}.xlsx`
6
  )
7
}

这能保证页面筛选和报表口径一致。若导出接口另写一套参数，很容易出现“列表 16 条、Excel 200 条”的尴尬场面。

7. 本篇小结#

在联调阶段，我还专门检查了几个很容易遗漏的边界：查询接口返回空 rows 时仍要保留正确的 total；删除最后一页唯一记录后需要退回上一页；手机号、MMSI 等敏感列要根据权限决定是否完整展示；连续点击查询时不让旧请求覆盖新结果。列表页虽然没有复杂动画，却是并发操作最频繁的页面之一。

接口层也保持“一个方法表达一个业务动作”，例如 approveDeliveryOrder、rejectDeliveryOrder、startFlight，而不是让页面到处调用通用 put。这样看到调用名就知道它会改变什么状态，也方便后续增加权限确认和敏感操作审计。

最后，我用下面这条数据流检查整个页面：

1
筛选表单 → queryParams → list API → rows/total
2
    ↓                               ↓
3
重置页码                        状态元数据
4
                                    ↓
5
                            表格标签与合法操作
6
                                    ↓
7
                        Layout 下的订单详情路由

订单列表真正困难的部分不是表格，而是把查询、分页、枚举、操作权限和路由上下文组织成一套稳定规则。写完后我对它的评价是：长得最朴素，管得却最多，像办公室里那个不声不响但谁都离不开的同事。

第三方平台接口的签名、缓存与降级

Fri, 31 Jul 2026 00:00:00 GMT

接入第三方接口时，最容易完成的是“请求成功一次”，最难的是让它长期稳定地处在业务链路中。微信和大疆接口形式不同，但都需要处理密钥、超时、错误响应、字段变化和临时不可用。

1. 密钥只停留在服务端#

AppSecret、SecretKey 等凭据放在服务端配置，通过 @Value 或配置属性对象注入。前端只调用自己的业务接口，不直接获得第三方密钥，也不负责签名。

配置预览接口只能返回“是否已配置”和请求头名称，不能把真实 AccessKey 或 SecretKey返回给页面。

2. 建立统一 HTTP 客户端#

第三方每个业务方法都自己创建请求，会重复出现超时、请求头、序列化和异常判断。通用客户端应统一负责：

基础地址与路径拼接；
查询参数、表单和 JSON 编码；
连接超时与请求超时；
鉴权请求头或 Token；
非 2xx 响应转换；
空响应与 JSON 解析；
不泄露密钥的日志。

平台 Service 再在客户端之上表达 getWayline、createTask 等业务能力。

3. 请求签名的动态字段#

大疆客户端每次请求生成时间戳与随机 nonce，再计算签名。动态字段可以降低请求被直接重放的风险：

1
method + timestamp + nonce
2
  -> HMAC 签名
3
  -> AccessKey、Timestamp、Nonce、Signature 请求头

签名原文的字段顺序、大小写和编码必须严格按平台协议，路径参数也要单独进行 URL 编码。

4. Token 缓存提前失效#

微信手机号接口依赖全局 access_token。每次请求都重新获取会增加延迟并浪费调用额度，因此可以在服务进程内缓存，并在官方过期时间前留出安全窗口。

1
cacheExpire = now + (expiresIn - 300) * 1000L;

本地缓存适合当前单体部署；多实例部署时，各实例独立刷新可能增加请求量，可进一步迁移到 Redis 并加互斥刷新。

5. 重试必须有限且有依据#

并不是所有错误都值得重试：

错误	策略
Token 明确失效	清缓存后重试一次
参数或模板错误	直接失败并记录原因
网络瞬时异常	对幂等查询有限重试
创建任务等非幂等操作	先确认平台是否已受理，不能盲目重发

无限重试会延长接口占用，并可能在外部服务恢复时制造流量洪峰。

6. 在边界处归一化字段#

第三方响应常出现字段命名或嵌套层级差异。适配层可以使用候选字段读取并转成项目自己的模型：

1
longitude / lng / lon -> longitude
2
latitude / lat        -> latitude
3
list / rows / records -> items

归一化应该集中在第三方边界，不要把兼容判断散到 Controller 和前端页面。

7. 按业务重要性设计降级#

订单轨迹页获取完整航线失败时，可以退回到接驳点和船舶位置，订单详情仍然可用；但创建飞行任务失败时，不能伪装成功。

可以用一个问题判断是否降级：

缺少这份第三方数据，核心业务事实是否仍然成立？

若只是展示增强，可以回退并标注数据来源；若会改变资金、订单或真实设备状态，就应明确失败并进入补偿流程。

8. 通用客户端怎样隐藏协议细节#

业务层希望调用的是：

1
djiOpenApiService.getWayline(waylineId, params);
2
djiOpenApiService.startTask(taskId, params);
3
wechatService.sendOrderArrivedMessage(order);

它不应该重复编写时间戳、请求头、JSON 序列化和 HTTP 状态判断。大疆客户端把这些逻辑集中到 request：

1
String method = rawMethod.toUpperCase(Locale.ROOT);
2
HttpRequest request = buildRequest(
3
        method, path, body, contentType);
4
HttpResponse<String> response = httpClient.send(
5
        request,
6
        HttpResponse.BodyHandlers.ofString(
7
                StandardCharsets.UTF_8));
8
if (response.statusCode() < 200
9
        || response.statusCode() >= 300) {
10
    throw new ServiceException("第三方服务响应异常");
11
}
12
return StringUtils.isEmpty(response.body())
13
        ? Collections.emptyMap()
14
        : objectMapper.readValue(response.body(), Object.class);

业务 Service 因而只关心平台能力和业务对象，协议变化集中修改客户端。测试时也可以替换客户端，模拟成功、超时和错误响应。

9. HMAC 签名具体在保护什么#

1
String timestamp = String.valueOf(
2
        System.currentTimeMillis());
3
String nonce = UUID.randomUUID()
4
        .toString().replace("-", "");
5
String signText = accessKey + method + timestamp + nonce;
6

7
Mac mac = Mac.getInstance("HmacSHA256");
8
mac.init(new SecretKeySpec(
9
        secretKey.getBytes(StandardCharsets.UTF_8),
10
        "HmacSHA256"));
11
String signature = toHex(mac.doFinal(
12
        signText.getBytes(StandardCharsets.UTF_8)));

AccessKey 用于标识调用方，SecretKey 参与 HMAC 但不随请求发送。时间戳限制签名有效窗口，nonce 让同一毫秒内的两次请求也有不同签名。

签名能证明请求由持有 SecretKey 的一方生成，但是否真正防重放还取决于平台是否校验时间窗口并保存近期 nonce。客户端不能只生成字段就假设服务端一定执行了这些规则。

10. access_token 缓存的并发细节#

1
private synchronized String getAccessToken() {
2
    long now = System.currentTimeMillis();
3
    if (StringUtils.isNotEmpty(cachedAccessToken)
4
            && cachedAccessTokenExpireTime > now) {
5
        return cachedAccessToken;
6
    }
7
    JsonNode tokenResult = requestAccessToken();
8
    int expiresIn = tokenResult.path("expires_in")
9
            .asInt(7200);
10
    cachedAccessToken = tokenResult.path("access_token")
11
            .asText();
12
    cachedAccessTokenExpireTime = now
13
            + Math.max(60, expiresIn - 300) * 1000L;
14
    return cachedAccessToken;
15
}

展开收起

volatile 保证其他线程能看到更新后的 Token 与时间，synchronized 保证只有一个线程进入刷新过程。由于同步范围只在缓存失效时执行，大部分命中请求不会访问第三方。

多实例部署后每个实例仍会各自刷新。可以把 Token 放入 Redis，并使用短期分布式锁控制刷新；读取缓存时还要处理锁持有者崩溃和 Token 即将过期的情况。

11. 重试前先判断请求是否幂等#

查询航线失败后重试通常不会产生新业务数据；创建任务失败后直接重试则可能创建两份任务。可以先为方法分类：

1
boolean retryable = switch (operation) {
2
    case LIST_DEVICE, GET_WAYLINE, QUERY_TASK -> true;
3
    case CREATE_TASK, START_TASK, SEND_MESSAGE -> false;
4
};

真正实现时还要结合错误类型：连接尚未建立通常可以重试，读取响应时断开则无法确定第三方是否已处理。非幂等动作需要业务请求号或状态查询来确认。

退避时间可以采用指数增长并加入随机抖动：

1
第 1 次失败：约 200ms 后重试
2
第 2 次失败：约 500ms 后重试
3
第 3 次失败：约 1000ms 后停止

随机抖动避免大量请求同时恢复后再次形成流量尖峰。

12. 字段归一化怎样限制变化范围#

1
private Object pickFirst(
2
        Map<String, Object> source,
3
        String... keys) {
4
    for (String key : keys) {
5
        Object value = source.get(key);
6
        if (value != null
7
                && !String.valueOf(value).trim().isEmpty()) {
8
            return value;
9
        }
10
    }
11
    return null;
12
}

调用时把 longitude、lng 和 lon 归一为项目字段 longitude。如果平台把列表从 list 改为 records，只需扩展适配层候选项。

不过兼容不能无限增加。字段语义改变时应建立新版本适配并记录告警，否则“能取到值”不代表值仍代表同一含义。

13. 降级结果也要说明数据来源#

订单轨迹从大疆获取成功时返回：

1
{
2
  "routeCoordinateSystem": "WGS84",
3
  "waylinePoints": [
4
    { "longitude": 120.1, "latitude": 30.2, "height": 80 }
5
  ]
6
}

降级到订单起终点时返回 GCJ02 和两个基础点。坐标系字段告诉前端两种结果不能直接按相同方式绘制。

还可以增加 routeSource: DJI | ORDER_FALLBACK 与 routeDegraded: true，让页面决定是否显示“当前展示预计路线”，也方便日志和监控统计降级比例。

14. 熔断和限流适合解决什么#

当第三方持续超时时，继续让每个订单详情等待 8 秒会耗尽 Web 线程。熔断器会在连续失败达到阈值后暂时快速失败，等待恢复窗口再放少量探测请求。

限流则控制单位时间内主动发出的请求量，避免超过平台配额。两者解决的问题不同：

机制	目标
超时	限制单个请求等待时间
重试	恢复短暂且可安全重试的失败
熔断	第三方持续故障时保护自身资源
限流	控制调用速率与平台配额
降级	在缺少增强数据时维持核心功能

这些机制应按接口单独配置，不能给查询航线和启动真实任务使用完全相同的策略。

15. 可观测性至少记录什么#

第三方调用日志建议包含：

1
provider=dji
2
operation=getWayline
3
requestId=项目侧追踪号
4
remoteRequestId=第三方响应追踪号
5
durationMs=183
6
status=success/failure/degraded
7
errorCode=平台错误码

不要记录 SecretKey、完整 Token、签名和用户 openid。业务日志与敏感信息脱敏并不冲突：只要有稳定请求号、操作名、耗时和错误码，已经可以完成大部分定位。

16. 小结#

稳定的第三方接入需要把凭据、协议和字段差异封装在边界内，再配合缓存、有限重试和分级降级。目标不是隐藏所有错误，而是让错误以符合业务重要性的方式发生。

后端接口的资源归属与文件安全

Tue, 28 Jul 2026 00:00:00 GMT

接口已经要求登录，不代表用户只能访问自己的数据。只要路径里出现订单 ID、地址 ID、凭证 ID，就需要防止用户替换 ID 后读取或修改别人的资源。这类检查属于对象级权限，不能只靠角色权限解决。

1. 当前用户只能来自安全上下文#

用户端查询条件不要接受可自由修改的 wxUserId：

1
Long currentUserId = SecurityUtils.getUserId();
2
query.setWxUserId(currentUserId);

请求体即使带了用户 ID，也应忽略或覆盖。前端字段适合表达用户想做什么，不适合作为“用户是谁”的证据。

2. 先查资源，再检查归属#

以修改地址为例：

1
读取 addressId 对应记录
2
  -> 检查记录存在且未删除
3
  -> 比较记录 wxUserId 与当前 userId
4
  -> 只更新允许修改的字段

凭证读取要先从 proofId 找到 orderId，再检查订单归属。间接资源同样不能因为没有直接的用户字段就跳过校验。

3. 列表和详情都要隔离#

详情接口容易想到归属校验，列表接口更容易遗漏。如果 Mapper 接收的是通用查询实体，前端可能通过参数覆盖用户条件。

更稳妥的做法是在 Service 中强制设置当前用户，并对用户端建立语义明确的方法，例如：

1
selectUserDeliveryOrderList(query)
2
selectCurrentUserDeliveryProofVoList(orderId)
3
selectUserNotificationList(query)

方法名本身提醒实现者必须处理用户边界。

4. 最小字段写入#

实体类经常包含状态、删除标记、审核字段和管理员备注。直接把请求实体交给 Mapper，可能让普通用户修改不该修改的数据。

应新建保存对象并显式复制白名单字段：

1
HyUserAddress save = new HyUserAddress();
2
save.setWxUserId(currentUserId);
3
save.setReceiverName(request.getReceiverName());
4
save.setReceiverPhone(request.getReceiverPhone());
5
save.setLongitude(request.getLongitude());
6
save.setLatitude(request.getLatitude());

读取时同样使用 VO 隐藏 storagePath、密钥、内部状态等字段。

5. 文件路径不是下载凭证#

数据库里的本地路径只能由后端解释。文件解析时至少完成：

只接受系统资源前缀；
使用配置的 profile 目录作为根；
对根目录和目标路径执行绝对化、规范化；
确认目标仍以根目录开头；
确认目标是普通文件；
根据资源归属通过鉴权接口输出文件流。

target.startsWith(root) 是阻止 ../ 路径穿越的关键，但它不能替代前面的订单归属校验。

6. 错误信息也要克制#

对无权访问和资源不存在返回过于不同的细节，可能帮助攻击者枚举有效 ID。业务上可以统一提示“资源不存在或无权访问”，服务端日志再保留具体原因。

文件响应还应使用可靠的 Content-Type，默认回退为 application/octet-stream，文件名需要正确编码，避免响应头被特殊字符破坏。

7. 一个通用的资源归属检查#

订单归属校验可以集中成明确的私有方法：

1
private void checkUserOrderOwner(
2
        HyDeliveryOrder order,
3
        Long wxUserId,
4
        String message) {
5
    if (order == null || "2".equals(order.getDelFlag())) {
6
        throw new ServiceException("订单不存在");
7
    }
8
    if (!wxUserId.equals(order.getWxUserId())) {
9
        throw new ServiceException(message);
10
    }
11
}

调用方必须先从数据库读取订单，不能用请求体里的 wxUserId 自己构造一个实体再校验。删除标记也在这里统一判断，逻辑删除后的资源对用户来说等同不存在。

如果希望避免泄露订单 ID 是否真实存在，可以把两个分支都返回“订单不存在或无权访问”，服务端日志再区分原因。

8. 间接资源需要沿关系检查#

凭证记录本身没有微信用户 ID，因此检查路径是：

1
private void checkProofOwner(Long proofId) {
2
    HyDeliveryProof proof = proofMapper.selectById(proofId);
3
    if (proof == null) {
4
        throw new ServiceException("配送凭证不存在");
5
    }
6
    HyDeliveryOrder order = orderMapper.selectById(
7
            proof.getOrderId());
8
    checkUserOrderOwner(
9
            order,
10
            SecurityUtils.getUserId(),
11
            "只能访问当前登录用户的订单凭证");
12
}

异常反馈、支付记录和订单历史也属于间接资源。只验证它们存在还不够，必须沿外键找到拥有者。

为了减少每次两次查询，也可以在 Mapper 中使用 join 同时返回归属信息，但 Service 的语义仍应是“验证当前用户拥有该资源”。

9. DTO 白名单比黑名单可靠#

黑名单思路是接收整个实体，再把危险字段设为空：

1
request.setStatus(null);
2
request.setDelFlag(null);
3
request.setWxUserId(currentUserId);
4
mapper.update(request);

以后实体新增 verifyStatus，开发者若忘记加入黑名单，就会再次产生越权字段。白名单则只复制允许字段：

1
HyUserAddress update = new HyUserAddress();
2
update.setAddressId(request.getAddressId());
3
update.setWxUserId(currentUserId);
4
update.setReceiverName(request.getReceiverName());
5
update.setReceiverPhone(request.getReceiverPhone());
6
update.setVesselName(request.getVesselName());
7
update.setMmsi(request.getMmsi());
8
update.setLongitude(request.getLongitude());
9
update.setLatitude(request.getLatitude());

未来新增后台字段时，它默认不会进入写入路径。对于大型项目，可以使用专用 DTO 与映射器减少重复，但映射规则仍应是显式白名单。

10. 文件读取的完整检查顺序#

1
public FileStreamVo getCurrentUserDeliveryProofImage(
2
        Long proofId) {
3
    HyDeliveryProof proof = getExistingProof(proofId);
4
    checkCurrentUserOrderOwner(proof.getOrderId());
5
    return ProtectedFileUtils.resolveProfileFile(
6
            proof.getStoragePath());
7
}

这三步不能倒置：

使用业务 ID 查到数据库记录；
根据记录关系判断当前用户是否有权限；
只有通过权限后才解析服务器文件路径。

如果先允许客户端提交任意路径给 resolveProfileFile，即使目录穿越检查正确，也会把文件系统结构变成公开接口的一部分。

11. Path 规范化代码拆解#

1
Path root = Paths.get(SystemConfig.getProfile())
2
        .toAbsolutePath()
3
        .normalize();
4
Path target = root.resolve(relativePath).normalize();
5

6
if (!target.startsWith(root)) {
7
    throw new ServiceException("文件路径非法");
8
}
9
if (!Files.isRegularFile(target)) {
10
    throw new ServiceException("文件不存在");
11
}

toAbsolutePath 消除工作目录差异，normalize 去掉 . 并解析 ..，resolve 把业务相对路径限制在根目录之下。最后再比较规范化后的 Path 层级。

Files.isRegularFile 同时排除目录和大部分特殊文件。若部署环境允许符号链接，还需要根据安全要求决定是否调用 toRealPath 并再次比较真实路径，避免链接指向根目录之外。

12. 文件响应头分别解决什么#

1
response.setContentType(file.getContentType());
2
response.setHeader("Cache-Control", "private, max-age=300");
3
response.setHeader(
4
        "Content-Disposition",
5
        "inline; filename=\"" + encodedName + "\"");
6
Files.copy(file.getPath(), response.getOutputStream());

Content-Type 告诉客户端如何解释字节；
private 阻止代理和公共 CDN 缓存私有订单图片；
max-age=300 允许当前用户客户端短时复用；
inline 表示优先预览，而不是强制下载；
文件名编码避免中文或特殊字符破坏响应头。

高敏感文件还可以使用 Cache-Control: no-store。选择缓存策略时要同时考虑隐私和小程序重复加载体验。

13. 对象级权限的测试清单#

每类资源至少验证以下场景：

1
当前用户 + 自己的有效资源       -> 成功
2
当前用户 + 其他用户资源         -> 拒绝
3
当前用户 + 已逻辑删除资源       -> 拒绝
4
未登录请求                     -> 在安全过滤器处拒绝
5
普通用户 + 管理端接口           -> 权限拒绝
6
管理员 + 鉴权文件接口           -> 按管理端规则读取
7
包含 ../ 的异常存储路径          -> 路径解析拒绝
8
数据库记录存在但磁盘文件不存在  -> 返回文件不存在

这些用例比只验证“上传成功、下载成功”更能发现真正的安全边界问题。

14. 小结#

登录解决身份，资源归属解决对象权限，字段白名单解决过度写入，VO 解决过度返回，路径规范化解决文件系统边界。任何一层缺失，都可能让一个看似普通的 CRUD 接口越过用户数据边界。

实习笔记⑤

Tue, 28 Jul 2026 00:00:00 GMT

围绕凭证查询系统继续做功能完善和权限逻辑优化。涉及查询表单、账簿页面、导航栏上下文、动态路由、菜单权限、用户角色授权以及管理员默认账套等多个部分。

这轮需求的核心可以概括为一句话：

让凭证查询和账簿查询真正按照“单位 + 年度 + 用户权限”运行，并且让页面结构、路由结构和菜单权限保持一致。

最终完成的主要内容包括：

优化凭证查询表单结构和筛选逻辑
新增并拆分账簿管理下的三个页面：总账、明细账、科目余额表
调整导航栏右上角单位和年度选择器
接入当前登录用户负责单位接口，实现不同用户看到不同单位
管理员默认拥有所有单位查看权限
管理员首次进入系统默认渲染 1000 + 2006 数据库状态
将凭证查询、总账、明细账、科目余额表归入菜单管理动态路由
批量配置已有用户角色权限，使所有已有用户可以访问四个业务页面
优化数据库不存在时的错误处理，不再弹出全局错误消息，而是在页面中渲染 404
修复导航栏下拉框抖动和下拉列表过高的问题

1. 凭证查询模块优化#

1.1 模块概述#

凭证查询模块主要位于：

1
src/views/query/voucher

本轮继续在上一周的基础上优化查询体验和页面结构，主要涉及以下文件：

文件	功能
`src/views/query/voucher/index.vue`	凭证查询列表页，负责查询表单、分组表格、查看入口和 404 状态渲染
`src/views/query/voucher/detail.vue`	查看凭证详情页，负责凭证展示和上一张/下一张切换
`src/views/query/voucher/components/VoucherSheet.vue`	记账凭证展示组件
`src/api/query/voucher.js`	凭证查询接口封装

1.2 查询表单结构调整#

凭证查询表单从原来的点击日期文本框展开查询面板，调整为和账簿管理页面一致的“标题 + 查询表单 + 表格”结构。

最终保留的查询条件主要包括：

查询条件	字段	说明
凭证字号	`pzh`	输入凭证字号进行查询
起始期间	`startMonth`	下拉选择起始会计期间
结束期间	`endMonth`	下拉选择结束会计期间
摘要	`zy`	支持按摘要模糊查询

单位代码和会计年度不再放在查询表单中，而是统一由导航栏右上角的全局上下文提供：

1
function buildVoucherQuery({ withPagination = true } = {}) {
2
  return compactQuery({
3
    ...(withPagination ? { pageNum: 1, pageSize: 10000 } : {}),
4
    dwdm: accountContextStore.dwdm,
5
    dwmc: accountContextStore.dwmc,
6
    year: accountContextStore.year,
7
    ...periodQueryOf(),
8
    pzh: String(queryParams.pzh || "").trim(),
9
    zy: String(queryParams.zy || "").trim()
10
  })
11
}

这样做的好处是：

四个业务模块统一使用同一个单位和年度上下文
查询表单更简洁，不再重复出现单位代码和会计年度
后续切换单位或年度时，页面可以自动刷新当前模块数据

1.3 查询请求方式#

凭证查询仍然复用已有后端接口：

1
export function listVoucher(query) {
2
  return request({
3
    url: '/voucher/list',
4
    method: 'get',
5
    params: query,
6
    hideErrorMessage: true
7
  })
8
}

这里增加了 hideErrorMessage: true，用于配合数据库不存在时的局部 404 页面。

当选择的单位和年度对应数据库不存在时，不再让全局拦截器弹出红色错误消息，而是在页面内部捕获错误：

1
function isDatabaseMissingError(error) {
2
  const message = String(error?.message || error || "")
3
  return /数据库|不存在|Unknown database|doesn'?t exist|404/i.test(message)
4
}

如果判断为数据库不存在，则设置：

1
databaseMissing.value = true

然后页面渲染：

1
<Error404 v-if="databaseMissing" class="voucher-error-page" />
2
<div v-else class="voucher-table-wrapper">
3
  <!-- 凭证表格 -->
4
</div>

这样用户看到的是一个明确的 404 页面，而不是突兀的全局错误弹窗。

1.4 首次进入不自动查询#

普通用户首次进入系统时，默认不选中单位和年度。凭证查询页也因此不能立即发起查询，否则会出现参数缺失。

处理方式是增加全局上下文判断：

1
const hasContext = computed(() =>
2
  Boolean(accountContextStore.dwdm && accountContextStore.year)
3
)

只有当单位和年度都选中后才查询：

1
if (hasContext.value) {
2
  getList({ silent: true })
3
}

同时监听单位和年度变化：

1
watch(
2
  () => [accountContextStore.dwdm, accountContextStore.year],
3
  () => {
4
    queryParams.pageNum = 1
5
    sourceRows.value = []
6
    databaseMissing.value = false
7
    if (hasContext.value) {
8
      getList({ silent: true })
9
    }
10
  }
11
)

这样页面不会在没有上下文时误请求，也不会频繁弹出“请选择单位和年度”的提示。

凭证查询表单优化后效果

2. 查看凭证页面布局优化#

查看凭证页面上一轮已经从弹窗改成独立路由页面，本轮主要继续调整布局，避免容器缩小时标题被左侧字段挤压。

2.1 问题现象#

页面中“记账凭证”主标题需要保持居中，副标题日期需要和主标题同行展示。但原布局中，左侧凭证字、凭证号、日期输入框占用空间较大，导致主标题被挤压。

2.2 优化思路#

优化后将标题区域看作一个独立的中间块：

主标题“记账凭证”保持视觉居中
副标题日期和主标题同行展示
左右两侧元信息不再影响标题位置
日期框长度缩小，避免小容器中撑开布局

布局上更倾向使用网格或弹性布局将页面划分为：

1
左侧凭证信息     中间标题区域     右侧附单据信息

这样容器变窄时，标题区域仍然有独立空间，不会因为左侧字段过长而偏移。

查看凭证标题布局优化后效果

3. 账簿管理模块#

3.1 模块拆分#

本轮新增并拆分了账簿管理相关页面。最初设计为一个“账簿管理”模块下包含三个子页面，后续根据菜单管理和动态路由需求，将三个页面独立成单独模块：

页面	路径	组件
总账	`ledger/general`	`ledger/general/index`
明细账	`ledger/detail`	`ledger/detail/index`
科目余额表	`ledger/balance`	`ledger/balance/index`

对应目录结构如下：

1
src/views/ledger
2
├── balance
3
│   └── index.vue
4
├── components
5
│   └── LedgerQueryPage.vue
6
├── detail
7
│   └── index.vue
8
└── general
9
    └── index.vue

其中 LedgerQueryPage.vue 是公共查询页组件，三个页面通过传入不同的接口和表格列配置实现复用。

3.2 公共组件设计#

公共组件的核心属性如下：

1
const props = defineProps({
2
  title: {
3
    type: String,
4
    required: true
5
  },
6
  request: {
7
    type: Function,
8
    required: true
9
  },
10
  columns: {
11
    type: Array,
12
    required: true
13
  },
14
  requireAccount: {
15
    type: Boolean,
16
    default: false
17
  },
18
  defaultAccountCode: {
19
    type: String,
20
    default: ""
21
  },
22
  showAccountOverview: {
23
    type: Boolean,
24
    default: false
25
  }
26
})

展开收起

属性	说明
`title`	页面标题，如总账、明细账
`request`	当前页面使用的查询接口
`columns`	表格列配置
`requireAccount`	是否必须选择科目
`defaultAccountCode`	默认科目代码
`showAccountOverview`	是否展示右侧科目总览列表

三个页面只需要维护自己的列配置：

1
<ledger-query-page
2
  title="总账"
3
  :request="listGeneralLedger"
4
  :columns="columns"
5
  empty-text="暂无总账数据"
6
/>

这种写法减少了重复代码，也方便后续继续扩展其他账簿页面。

3.3 明细账右侧科目列表#

明细账页面参考旧系统样式，在右侧增加科目代码和科目名称总览列表。用户点击某个科目后，自动带上科目代码查询明细账。

科目列表接口为：

1
export function listLedgerAccounts(query) {
2
  return request({
3
    url: '/voucher/km/list',
4
    method: 'get',
5
    params: query,
6
    hideErrorMessage: true
7
  })
8
}

请求参数由全局上下文提供：

1
const response = await listLedgerAccounts({
2
  dwdm: accountContextStore.dwdm,
3
  year: accountContextStore.year,
4
  pageNum: 1,
5
  pageSize: 10000
6
})

返回数据中科目名称字段为 kmmc，前端进行标准化处理：

1
function normalizeAccount(account) {
2
  return {
3
    ...account,
4
    kmdm: String(account?.kmdm || account?.accountCode || ""),
5
    kmmc: account?.kmmc || account?.accountName || ""
6
  }
7
}

默认展示科目代码 101 的明细账：

1
<ledger-query-page
2
  title="明细账"
3
  :request="listDetailLedger"
4
  :columns="columns"
5
  require-account
6
  show-account-overview
7
  default-account-code="101"
8
/>

明细账右侧科目列表

3.4 账簿接口封装#

账簿接口统一封装在：

1
src/api/ledger/index.js

函数	接口	说明
`listGeneralLedger`	`/voucher/generalLedger/list`	查询总账
`listDetailLedger`	`/voucher/detailLedger/list`	查询明细账
`listAccountBalance`	`/voucher/accountBalance/list`	查询科目余额表
`listLedgerAccounts`	`/voucher/km/list`	查询科目列表

这些接口都增加了：

1
hideErrorMessage: true

原因和凭证查询一样：当单位年度对应数据库不存在时，由页面内部渲染 404，而不是使用全局弹窗。

4. 导航栏单位与年度上下文#

4.1 从页面查询条件中抽离公共参数#

凭证查询、总账、明细账、科目余额表四个页面都需要：

单位代码 dwdm
单位名称 dwmc
会计年度 year

如果每个页面都放一套单位和年度查询条件，不仅重复，而且容易造成状态不一致。因此本轮将这两个公共条件抽离到导航栏右上角。

涉及文件：

文件	功能
`src/layout/components/Navbar.vue`	展示单位和年度下拉框
`src/store/modules/accountContext.js`	保存当前单位和年度上下文
`src/api/accountContext.js`	封装单位和年度相关接口

4.2 状态管理#

accountContext store 的核心状态如下：

1
state: () => ({
2
  unitOptions: [],
3
  yearOptions: [],
4
  dwdm: '',
5
  dwmc: '',
6
  year: '',
7
  loadingUnits: false,
8
  loadingYears: false
9
})

状态	说明
`unitOptions`	当前用户可选择的单位列表
`yearOptions`	当前单位可选择的年度列表
`dwdm`	当前单位代码
`dwmc`	当前单位名称
`year`	当前会计年度
`loadingUnits`	单位加载状态
`loadingYears`	年度加载状态

普通用户首次进入系统时，默认不选中单位和年度：

1
dwdm: '',
2
dwmc: '',
3
year: ''

这样可以避免在用户还没有选择上下文时误请求后端。

4.3 年度列表返回全部数据#

年度接口默认只返回 10 条数据，原因是若依分页默认值生效。原请求只传了：

1
{ dwdm: this.dwdm }

优化后改为：

1
const response = await listYears({
2
  dwdm: this.dwdm,
3
  pageNum: 1,
4
  pageSize: 10000
5
})

这样年度下拉框可以拿到完整年份列表，不会只展示前 10 条。

4.4 下拉框抖动优化#

单位名称较长时，点击选择后会撑开导航栏，导致页面抖动。优化方式是：

单位和年度按钮固定宽度
文本超出显示省略号
下拉列表限制高度
下拉项过多时内部滚动

核心样式如下：

1
.context-button {
2
  display: inline-flex;
3
  align-items: center;
4
  justify-content: space-between;
5
  height: 32px;
6
  box-sizing: border-box;
7
  overflow: hidden;
8
}
9

10
.unit-context-button {
11
  width: 176px;
12
}
13

14
.context-value {
15
  flex: 1 1 auto;
16
  overflow: hidden;
17
  min-width: 0;
18
  text-overflow: ellipsis;
19
  white-space: nowrap;
20
}
21

22
:global(.account-context-dropdown .el-dropdown-menu) {
23
  max-height: 320px;
24
  overflow-y: auto;
25
  overflow-x: hidden;
26
}

展开收起

导航栏单位和年度下拉框

5. 用户单位权限#

5.1 普通用户单位权限#

后端新增接口：

1
GET /voucher/unit/current-user/list

用于获取当前登录用户负责的单位列表。这个接口不需要前端传 userid，而是通过登录态中的 token 判断当前用户。

前端封装如下：

1
export function listCurrentUserUnits() {
2
  return request({
3
    url: '/voucher/unit/current-user/list',
4
    method: 'get'
5
  })
6
}

普通用户加载单位时调用：

1
const response = await listCurrentUserUnits()

这样不同账号登录后，单位下拉框中看到的单位列表会不同。

5.2 单位字段兼容#

为了兼容不同接口返回结构，前端对单位数据做了标准化处理：

1
function normalizeUnit(unit) {
2
  if (typeof unit === 'string' || typeof unit === 'number') {
3
    const value = String(unit)
4
    const [code, ...nameParts] = value.split('-')
5
    return {
6
      dwdm: code || value,
7
      dwmc: nameParts.join('-') || value
8
    }
9
  }
10
  return {
11
    ...unit,
12
    dwdm: String(unit?.dwdm || unit?.unitCode || unit?.code || unit?.value || ''),
13
    dwmc:
14
      unit?.dwmc ||
15
      unit?.unitName ||
16
      unit?.name ||
17
      unit?.label ||
18
      unit?.dwdm ||
19
      unit?.unitCode ||
20
      unit?.code ||
21
      unit?.value ||
22
      ''
23
  }
24
}

展开收起

支持的返回结构包括：

1
{ dwdm, dwmc }
2
{ code, name }
3
{ value, label }
4
"1000-单位名称"
5
"1000"

5.3 登出清理上下文#

为了避免切换账号后仍然残留上一个账号的单位列表，登出时清空 accountContext：

1
useAccountContextStore().resetContext()

对应方法：

1
resetContext() {
2
  this.unitOptions = []
3
  this.loadingUnits = false
4
  this.loadingYears = false
5
  this.clearContext()
6
}

这一步虽然很小，但对权限类功能很重要。否则在同一个浏览器会话中切换用户时，可能短暂显示上一个用户的单位数据。

6. 管理员默认账套逻辑#

6.1 需求变化#

后续需求调整为：

当登录态为管理员权限时，默认拥有所有单位的查看权限，并且默认渲染 1000 + 2006 单位数据库状态。

这里需要区分普通用户和管理员：

用户类型	单位来源	是否默认选中
普通用户	`/voucher/unit/current-user/list`	不默认选中
管理员	`/voucher/unit/list`	默认选中 `1000 / 2006`

6.2 管理员判断#

项目中已有权限工具约定：

角色包含 admin 表示管理员
权限包含 *:*:* 表示拥有全部权限

因此在导航栏中计算：

1
const isAdminUser = computed(() => {
2
  return userStore.roles.includes('admin') ||
3
    userStore.permissions.includes('*:*:*')
4
})

初始化上下文时传入：

1
accountContextStore.initialize({
2
  isAdmin: isAdminUser.value
3
})

6.3 管理员加载全部单位#

API 封装：

1
export function listUnits(query) {
2
  return request({
3
    url: '/voucher/unit/list',
4
    method: 'get',
5
    params: query
6
  })
7
}

管理员加载单位时：

1
const response = isAdmin
2
  ? await listUnits({ pageNum: 1, pageSize: 10000 })
3
  : await listCurrentUserUnits()

6.4 默认选中 1000 和 2006#

在 accountContext 中定义默认值：

1
const ADMIN_DEFAULT_UNIT_CODE = '1000'
2
const ADMIN_DEFAULT_YEAR = '2006'

管理员加载单位后，如果当前没有选中单位，则自动选中默认单位：

1
const defaultUnit =
2
  units.find((unit) => unit.dwdm === ADMIN_DEFAULT_UNIT_CODE) || units[0]
3

4
if (defaultUnit) {
5
  this.dwdm = defaultUnit.dwdm
6
  this.dwmc = defaultUnit.dwmc
7
  this.year = ADMIN_DEFAULT_YEAR
8
}

这样管理员登录后页面会自动进入：

1
dwdm = 1000
2
year = 2006

也就是默认渲染 10002006 单位数据库状态。

7. 动态路由与菜单权限#

7.1 项目动态路由机制#

本项目使用若依前端的动态路由机制。登录后在 src/permission.js 中执行：

1
const accessRoutes = await usePermissionStore().generateRoutes()

generateRoutes 内部请求后端：

1
getRouters()

也就是：

1
GET /getRouters

后端返回菜单路由后，前端通过 filterAsyncRouter 转换组件：

1
function filterAsyncRouter(asyncRouterMap, lastRouter = false, type = false) {
2
  return asyncRouterMap.filter(route => {
3
    if (route.component) {
4
      if (route.component === 'Layout') {
5
        route.component = Layout
6
      } else if (route.component === 'ParentView') {
7
        route.component = ParentView
8
      } else if (route.component === 'InnerLink') {
9
        route.component = InnerLink
10
      } else {
11
        route.component = loadView(route.component)
12
      }
13
    }
14
    return true
15
  })
16
}

展开收起

组件路径通过 loadView 映射到 src/views：

1
export const loadView = (view) => {
2
  let res
3
  for (const path in modules) {
4
    const dir = path.split('views/')[1].split('.vue')[0]
5
    if (dir === view) {
6
      res = () => modules[path]()
7
    }
8
  }
9
  return res
10
}

所以菜单管理中填写：

1
ledger/general/index

就会映射到：

1
src/views/ledger/general/index.vue

7.2 四个业务页面归入菜单管理#

为了和凭证查询保持一致，总账、明细账、科目余额表不再写入 constantRoutes，而是统一通过菜单管理分配。

菜单配置如下：

菜单名称	路由地址	组件路径	权限标识
凭证查询	`query/voucher`	`query/voucher/index`	`query:voucher:list`
总账	`ledger/general`	`ledger/general/index`	`query:ledger:list`
明细账	`ledger/detail`	`ledger/detail/index`	`query:detail:list`
科目余额表	`ledger/balance`	`ledger/balance/index`	`query:balance:list`

前端只保留了查看凭证详情页的隐藏路由：

1
{
2
  path: '/voucher-detail',
3
  component: Layout,
4
  hidden: true,
5
  redirect: '/query/voucher',
6
  children: [
7
    {
8
      path: ':pzh',
9
      component: () => import('@/views/query/voucher/detail'),
10
      name: 'VoucherDetail',
11
      meta: {
12
        title: '查看凭证',
13
        activeMenu: '/query/voucher',
14
        noCache: true
15
      }
16
    }
17
  ]
18
}

展开收起

原因是查看凭证属于凭证查询的内部详情页，不应该作为菜单项分配。

7.3 批量配置已有用户权限#

角色管理中已有两个角色：

角色 ID	角色名称	权限字符
`1`	超级管理员	`admin`
`2`	普通角色	`common`

本轮直接通过后端接口完成权限数据调整：

将普通角色 roleId=2 的菜单权限补齐为：

1
2000, 2001, 2002, 2003

检查已有用户授权情况：

1
已有用户总数：125
2
超级管理员：admin，默认全部权限
3
普通角色已授权用户：124
4
剩余未授权用户：仅 admin

也就是说，已有用户都可以访问：

1
凭证查询
2
总账
3
明细账
4
科目余额表

菜单管理中四个业务页面配置

8. 全局错误处理优化#

8.1 原问题#

当用户选择某个单位和年度后，前端会根据两者拼接查询对应数据库。如果该数据库不存在，后端会返回错误。

优化前，错误会被全局请求拦截器捕获并弹出：

1
ElMessage({ message: msg, type: 'error' })

这类弹窗的问题是：

错误信息对普通用户不友好
每次切换单位或年度都可能弹出
用户无法明确知道当前页面没有对应数据库

8.2 增加静默错误配置#

在 src/utils/request.js 中支持：

1
hideErrorMessage: true

当接口配置了该字段时，全局拦截器不再弹出错误消息：

1
const hideErrorMessage =
2
  res.config?.hideErrorMessage === true ||
3
  res.config?.headers?.hideErrorMessage === true
4

5
if (code === 500) {
6
  if (!hideErrorMessage) {
7
    ElMessage({ message: msg, type: 'error' })
8
  }
9
  return Promise.reject(new Error(msg))
10
}

网络错误分支同样处理：

1
if (!hideErrorMessage) {
2
  ElMessage({
3
    message: message,
4
    type: 'error',
5
    duration: 5 * 1000
6
  })
7
}

8.3 页面内部渲染 404#

凭证查询和账簿查询页面捕获错误后，判断是否属于数据库不存在：

1
function isDatabaseMissingError(error) {
2
  const message = String(error?.message || error || "")
3
  return /数据库|不存在|Unknown database|doesn'?t exist|404/i.test(message)
4
}

如果是，则渲染：

1
<Error404 />

这样用户看到的是页面状态，而不是全局弹窗。

9. 技术要点总结#

9.1 动态路由不等于公共路由#

一开始总账、明细账、科目余额表曾经被写入 constantRoutes，这样虽然页面可以访问，但会绕过后端菜单管理和角色权限分配。

本轮调整后，四个业务页面都通过菜单管理返回：

1
/getRouters -> filterAsyncRouter -> router.addRoute

这更符合后台权限系统的设计。

9.2 全局上下文减少重复查询条件#

单位和年度是四个业务页面共同依赖的参数，因此放在导航栏统一管理更合适。

这样页面查询只需要关心自己的业务条件，例如：

凭证字号
摘要
起止期间
科目代码

公共条件由 accountContextStore 注入。

9.3 管理员和普通用户分流#

同一个单位下拉框，在不同登录态下有不同数据来源：

1
const response = isAdmin
2
  ? await listUnits({ pageNum: 1, pageSize: 10000 })
3
  : await listCurrentUserUnits()

这样既保证了管理员拥有全量查看能力，又保留了普通用户的单位权限控制。

9.4 页面级 404 比全局 error 更适合业务状态#

数据库不存在不是前端崩溃，而是一种业务状态。将它渲染成页面状态，比弹出错误消息更稳定，也更容易让用户理解当前单位年度不可用。

9.5 下拉框稳定性也会影响使用体验#

导航栏中的单位名称经常很长，如果不限制宽度，选择后会造成页面抖动。通过固定宽度、文本省略和下拉列表滚动，可以让导航栏交互更加稳定。

10. 本周总结#

本周的工作不像上一周那样只集中在一个页面，而是从“页面展示”逐渐深入到“系统上下文”和“权限体系”。

这次最重要的收获有三点：

动态路由要和菜单权限保持一致
业务页面不应该随意写入公共路由，否则会绕过角色权限体系。
公共参数适合抽离成全局上下文
单位和年度被多个模块共享，放到导航栏统一选择，比每个页面重复维护更清晰。
权限逻辑要区分普通用户和管理员
普通用户只看自己负责的单位，管理员则拥有全部单位权限，并默认进入指定账套状态。

这一轮改动让我对后台系统里的“路由、菜单、角色、用户、业务查询参数”之间的关系理解更清楚了。页面功能看起来只是几个下拉框和几张表，但背后其实串起了前端路由、后端菜单、用户权限、接口参数和错误状态处理。

这周的感觉像是在给系统补“骨架”：页面只是表面，真正要稳的是路由和权限这条主线。

后端业务状态流转与事务一致性

Sat, 25 Jul 2026 00:00:00 GMT

订单类系统最危险的接口往往不是查询，而是“下一步”。一次状态变化可能同时修改主记录、支付记录、历史快照、子订单和过程日志。只要其中一步失败，数据就可能进入前端无法表达的中间状态。

1. 把状态变化写成业务动作#

不要提供一个允许前端任意传 orderStatus 的通用接口。更安全的做法是为动作建立明确方法：

1
approve(orderId, action);
2
reject(orderId, action);
3
startFlight(orderId, action);
4
confirmDelivered(orderId, action);
5
refundCancel(exceptionId, action);

方法名表达意图，参数只包含该动作允许输入的内容，目标状态由 Service 内部确定。

2. 状态流转有三个要素#

每个动作都应回答三个问题：

要素	示例
前置状态	只有待审核订单才能审核通过
动作副作用	写审核人、时间、意见和过程日志
目标状态	审核通过后进入待调度

如果只检查目标状态，就会漏掉非法跳转。即使最终都要进入“已送达”，从待支付直接送达和从飞行中送达也不是同一件事。

3. 事务边界围绕业务动作#

事务不应该机械地包住所有 Service 方法，而应覆盖一次业务动作必须同时成立的数据：

1
@Transactional(rollbackFor = Exception.class)
2
public void pay(Long orderId) {
3
    insertPaymentRecord(orderId);
4
    updateOrderStatus(orderId, "WAIT_AUDIT");
5
    insertProcessLog(orderId, "PAY");
6
}

读取列表通常可以使用只读事务；退款、重派、设置默认地址等多步写操作则需要回滚能力。

4. 日志属于业务结果#

过程日志不是调试日志。它会被用户进度页和管理端详情读取，因此属于业务数据。订单已变成飞行中却没有 START_FLIGHT 记录，功能虽然“成功”，业务链路却不完整。

系统运行日志回答“程序发生了什么”，业务过程日志回答“订单发生了什么”，两者不要混用。

5. 幂等分层处理#

常见的防重复手段包括：

终态检查：已关闭工单不能再次处理；
结果关联检查：存在 resultOrderId 就不能再次生成重派单；
稳定业务编号：快照按 reportNo 更新或新增；
数据库唯一约束：用户 openId、业务单号等最终由数据库兜底；
条件更新：订阅额度只在 availableCount > 0 时扣减。

synchronized 只能限制当前 JVM 实例，部署多个实例后仍需要数据库约束或分布式控制。

6. 第三方调用放在哪里#

数据库事务无法回滚已经发给第三方的请求。若在事务中先调用外部平台、再写数据库，数据库失败时外部动作可能已经完成；反过来也可能出现数据库提交后消息发送失败。

需要先区分主事实：

订单状态、支付记录等核心数据应优先保证本地一致；
微信通知等附加动作可以记录失败并补偿；
真正启动飞行等不可轻易补偿的动作，需要设计请求号、状态确认和对账机制。

7. 条件更新把状态规则下沉到数据库#

Service 中的状态判断让错误提示更友好，但真正写入时还可以再次限制旧状态：

1
int rows = orderMapper.updateStatusIfMatch(
2
        orderId,
3
        "WAIT_DISPATCH",
4
        "DELIVERING",
5
        taskId,
6
        updateTime);
7
if (rows == 0) {
8
    throw new ServiceException(
9
            "订单状态已变化，请刷新后重试");
10
}

对应 SQL：

1
update hy_delivery_order
2
set order_status = #{targetStatus},
3
    current_task_id = #{taskId},
4
    update_time = #{updateTime}
5
where order_id = #{orderId}
6
  and order_status = #{expectedStatus}
7
  and del_flag = '0'

如果两个请求都读取到 WAIT_DISPATCH，只有第一个能把它更新为 DELIVERING。第二个执行时 where 条件已不成立，受影响行数为 0。

这是一种轻量乐观并发控制。另一种做法是在表中增加 version：

1
update hy_delivery_order
2
set ..., version = version + 1
3
where order_id = #{orderId}
4
  and version = #{oldVersion}

状态条件更适合只关心有限状态转换的业务，版本号更适合多个字段都可能被并发编辑的场景。

8. Spring 事务代理实际包住了什么#

下面的注解并不是让方法内部每一行自动变成“不可分割指令”：

1
@Transactional(rollbackFor = Exception.class)
2
public HyExceptionTicket refundCancel(...) {
3
    insertPaymentRecord(...);
4
    updateOrderStatus(...);
5
    updateTicketStatus(...);
6
    insertProcessLog(...);
7
}

Spring 在 Service Bean 外创建代理。Controller 调用代理方法时，代理先从事务管理器获取数据库连接并关闭自动提交，然后执行真实方法：

1
Controller
2
  -> TransactionInterceptor 开启事务
3
  -> ServiceImpl.refundCancel
4
  -> 多个 Mapper 共用当前线程绑定的连接
5
  -> 正常返回：commit
6
  -> 抛出匹配异常：rollback

因此事务能否生效取决于调用是否经过代理。下面这种同类内部调用可能绕过代理：

1
public void outer() {
2
    inner(); // this.inner()，不是通过 Spring 代理调用
3
}
4

5
@Transactional
6
public void inner() {
7
    // 事务可能不会按预期创建
8
}

可以把 inner 移到独立 Service，或把事务边界直接放在外部入口方法上。项目开启了 exposeProxy，虽然可以显式获取代理，但通常重新设计职责更清楚。

9. catch 异常为什么可能导致提交#

1
@Transactional(rollbackFor = Exception.class)
2
public void process() {
3
    mapper.insertA();
4
    try {
5
        mapper.insertB();
6
    } catch (Exception e) {
7
        log.error("insert B failed", e);
8
    }
9
}

异常被方法内部捕获且没有再次抛出，事务代理看到的是“方法正常返回”，于是会提交 insertA。如果 B 失败意味着整个业务失败，应重新抛出异常：

1
} catch (Exception e) {
2
    throw new ServiceException("处理失败", e);
3
}

也可以显式标记当前事务回滚，但让异常自然传播通常更易读。只有当 B 属于可忽略的附加动作时，才应该捕获后继续，并在代码中说明降级原因。

10. 事务传播用于表达动作嵌套#

Spring 默认传播行为是 REQUIRED：外层已有事务就加入，没有就新建。订单 Service 调用过程日志 Service 时，两者因此通常共享同一事务。

1
createOrder（开启事务）
2
  -> insert order
3
  -> processLogService.insert（加入当前事务）
4
  -> 一起提交或回滚

如果日志方法使用 REQUIRES_NEW，它会暂停外层事务并独立提交。之后订单回滚，日志却可能留下“订单创建成功”的错误记录。

独立事务适合必须保留的失败审计，但不适合描述尚未提交的业务事实。选择传播行为之前，要先确定内外两份数据是否必须共同成功。

11. 外部调用不能依赖数据库回滚#

下面的写法看起来在事务里，实际只能回滚数据库：

1
@Transactional
2
public void startFlight(Order order) {
3
    Object djiTask = djiClient.createTask(...);
4
    orderMapper.updateStatus(order.getId(), "DELIVERING");
5
}

大疆任务创建成功后，如果数据库更新失败，回滚不会向大疆自动发送删除任务请求。反过来先提交数据库，再调用第三方，又可能出现本地显示配送中但平台没有任务。

可以引入本地状态机和补偿：

1
本地任务 CREATING
2
  -> 提交事务
3
  -> 使用业务请求号调用第三方
4
  -> 成功：本地任务 READY，订单进入 DELIVERING
5
  -> 失败：本地任务 FAILED，允许人工或定时重试

请求号在第三方支持时作为幂等键；不支持时则需要在重试前查询平台是否已创建对应任务。

12. 用例测试应该覆盖哪些状态#

状态流转测试不能只验证成功路径。以支付为例，至少应覆盖：

1
UNPAID + 未超时       -> PENDING_AUDIT，新增一条支付记录
2
UNPAID + 已超时       -> CANCELED，不新增成功支付记录
3
PENDING_AUDIT + 重试  -> 状态不变，不重复新增支付记录
4
其他用户订单          -> 拒绝访问，数据库无变化
5
写日志失败            -> 订单和支付记录全部回滚

异常处置则要覆盖已关闭工单、重复重派、退款金额为空、过程日志插入失败和并发更新受影响行数为 0。

测试关注的是状态与副作用组合，而不是只断言 Service 返回了非空对象。

13. 小结#

可靠的状态流转不是多写几个 if。动作接口限制意图，前置条件限制路径，事务保证本地数据一起成功，幂等阻止重复执行，过程日志留下可追溯结果。五者组合起来，复杂流程才有稳定基础。

后端开发日记⑨：运营统计、报表快照与定时任务

Wed, 22 Jul 2026 00:00:00 GMT

数据大屏关注实时运营，报表页关注一段时间内的趋势。它们都来自订单数据，但时间窗口、聚合方式和保存策略不同。本篇记录统计接口如何把数据库结果整理成前端可以直接使用的结构。

1. 大屏汇总使用统一时间边界#

今日统计以系统时区的当天零点为开始、次日零点为结束，SQL 使用左闭右开区间：

1
[today 00:00:00, tomorrow 00:00:00)

这种写法比拼接 23:59:59 更稳定，不会遗漏带毫秒的数据。订单总数、待处理、飞行中、完成、取消与异常数量都使用同一组边界，避免指标之间口径不一致。

2. 查询结果需要补零#

数据库只返回有数据的小时。如果凌晨 3 点没有订单，原始结果里就没有这一项，前端折线会缩短或错位。

Service 先把原始结果转成 Map，再按完整时间序列逐点读取：

1
for (int hour = 0; hour < 24; hour++) {
2
    result.add(new Point(label(hour),
3
            rawMap.getOrDefault(key(hour), 0L)));
4
}

日报按小时、周报按天、月报按月都使用相同思路。时间轴完整性属于后端统计口径的一部分，不应让每个前端页面重复补齐。

3. 报表不仅是订单数量#

AdminReportSnapshotStatsVo 组合了多组数据：

订单总量、完成率、平均配送时长；
超时率、异常率、取消率；
快递与外卖占比；
当前周期趋势；
配送失败原因分布；
与上一周期的变化率。

除法统一处理分母为零的情况，百分比保留两位小数。上一周期为零而当前不为零时，变化率按约定返回 100%，避免直接除零。

4. 实时统计与快照分开#

日报、周报和月报接口可以实时查询当前周期；完整历史周期则由定时任务生成快照。快照把统计 VO 序列化为 JSON 存入 reportData，同时保存报表编号、类型、日期、标题与生成时间。

报表编号具有稳定格式：

1
DAY-20260825
2
WEEK-20260817
3
MONTH-202607

保存前先按报表编号查询，存在就更新，不存在才新增。这样任务重复执行不会产生两份同周期报表。

5. 定时任务只做触发#

ReportSnapshotTask 提供三个清晰入口：

1
saveDailyReportSnapshot();
2
saveWeeklyReportSnapshot();
3
saveMonthlyReportSnapshot();

它们分别保存上一日、上一完整周和上一完整月的数据。Quartz 负责何时调用，统计时间范围、数据组装和幂等落库仍由 Service 完成。

订单模块也使用相同方式处理 15 分钟未支付超时：调度类只传入规则参数，业务判断留在订单 Service。

6. 时间与时区#

统计使用 ZoneId.systemDefault() 把 LocalDateTime 转为数据库查询所需的 Date。部署环境的系统时区因此会影响报表边界，生产配置必须明确，不能默认所有机器都在同一时区。

周报以周一作为开始，月报以自然月第一天作为边界。只有把这些规则固定在后端，管理端切换周期时才不会产生各算各的情况。

7. 一条 SQL 同时计算多个状态#

大屏概览没有为每个状态分别查询数据库，而是使用条件聚合：

1
select
2
    count(1) as totalOrders,
3
    coalesce(sum(case
4
        when order_status = 'PENDING_AUDIT'
5
        then 1 else 0 end), 0) as pendingAuditOrders,
6
    coalesce(sum(case
7
        when order_status = 'WAIT_DISPATCH'
8
        then 1 else 0 end), 0) as waitDispatchOrders,
9
    coalesce(sum(case
10
        when order_status = 'DELIVERING'
11
        then 1 else 0 end), 0) as flyingOrders,
12
    coalesce(sum(case
13
        when order_status = 'COMPLETED'
14
        then 1 else 0 end), 0) as completedOrders
15
from hy_delivery_order
16
where del_flag = '0'
17
  and create_time >= #{startTime}
18
  and create_time < #{endTime}

展开收起

case when 把满足条件的行记为 1，不满足记为 0，再使用 sum 得到各状态数量。coalesce 把没有数据时的 null 转为 0，减少 Java 端空值分支。

所有指标共用同一个时间过滤和删除标记，既减少数据库往返，也保证统计口径一致。create_time 上应建立与常用条件匹配的索引，否则订单量增加后每日全表扫描会拖慢大屏。

8. 今日和昨日如何在 Service 组装#

1
ZoneId zoneId = ZoneId.systemDefault();
2
LocalDate today = LocalDate.now(zoneId);
3
Date todayStart = toDate(today, zoneId);
4
Date tomorrowStart = toDate(today.plusDays(1), zoneId);
5
Date yesterdayStart = toDate(today.minusDays(1), zoneId);
6

7
AdminOrderScreenCountVo todayCounts = normalize(
8
        mapper.selectOrderCounts(todayStart, tomorrowStart));
9
AdminOrderScreenCountVo yesterdayCounts = normalize(
10
        mapper.selectOrderCounts(yesterdayStart, todayStart));

三个边界点组成两个连续且不重叠的区间。使用 LocalDate.atStartOfDay(zoneId) 转为时间点，避免手动拼接日期字符串。

异常工单来自另一张表，因此单独统计后写入同一个 VO。这里再次体现 Service 的组装职责：Mapper 返回每张表擅长的原始统计，Service 形成页面需要的完整概览。

9. 环比计算怎样处理零分母#

1
private BigDecimal calculateRate(
2
        Long todayCount, Long yesterdayCount) {
3
    long today = nullToZero(todayCount);
4
    long yesterday = nullToZero(yesterdayCount);
5
    if (yesterday == 0L) {
6
        return today == 0L
7
                ? BigDecimal.ZERO.setScale(2)
8
                : BigDecimal.valueOf(100).setScale(2);
9
    }
10
    return BigDecimal.valueOf(today - yesterday)
11
            .multiply(BigDecimal.valueOf(100))
12
            .divide(BigDecimal.valueOf(yesterday),
13
                    2, RoundingMode.HALF_UP);
14
}

正常公式是 (今日 - 昨日) / 昨日 × 100%。昨日为零时数学上没有有限增长率，项目按展示约定返回 0 或 100。这个约定应该写进接口文档，避免前端误以为 100 表示严格数学结果。

使用 BigDecimal 而不是 double，并明确两位小数和四舍五入方式，保证不同页面得到一致结果。

10. 小时趋势为什么把分组值加一#

SQL 使用 hour(create_time) 得到 0—23：

1
select hour(create_time) as hourValue,
2
       count(1) as orderCount
3
from hy_delivery_order
4
where create_time >= #{startTime}
5
  and create_time < #{endTime}
6
group by hour(create_time)

Service 把数据库小时转换为区间终点：

1
int hourPoint = (raw.getHourValue() + 1) % 24;
2
countMap.put(hourPoint, raw.getOrderCount());

因此数据库的 0 点表示 0-1，在结果中使用 hourPoint = 1；23 点表示 23-24，使用 0 作为环形终点。buildPeriod(0) 特殊返回 23-24。

随后循环 0—23 补齐全部区间，没有订单的小时从 Map 取得默认值 0。前端拿到固定 24 个点，可以直接绘图。

11. 日、周、月三个时间窗口#

1
// 当日
2
LocalDateTime dayStart = today.atStartOfDay();
3
LocalDateTime dayEnd = today.plusDays(1).atStartOfDay();
4

5
// 最近七个自然日（含今天）
6
LocalDateTime weekStart = today.minusDays(6).atStartOfDay();
7
LocalDateTime weekEnd = today.plusDays(1).atStartOfDay();
8

9
// 当前自然月
10
LocalDate firstDay = today.withDayOfMonth(1);
11
LocalDateTime monthStart = firstDay.atStartOfDay();
12
LocalDateTime monthEnd = firstDay.plusMonths(1).atStartOfDay();

“周报”在实时页面中表示最近七天，在定时快照中表示上一完整自然周。两者名称相似但时间口径不同，文章和接口文档都需要说清楚。

上一周期使用与当前周期等长且紧邻的区间，才能比较订单量、完成率和平均时长。

12. 快照幂等代码拆解#

1
HyReportSnapshot existing = mapper
2
        .selectHyReportSnapshotByReportNo(reportNo);
3
if (existing == null) {
4
    mapper.insertHyReportSnapshot(snapshot);
5
} else {
6
    snapshot.setReportId(existing.getReportId());
7
    snapshot.setRegionId(existing.getRegionId());
8
    mapper.updateHyReportSnapshot(snapshot);
9
}
10
return mapper.selectHyReportSnapshotByReportNo(reportNo);

reportNo 是周期的稳定业务键。Quartz 因重启、人工补执行或失败重试再次运行时，会覆盖同周期快照，而不是新增重复记录。

数据库最好为 report_no 建唯一索引，防止两个调度实例同时查询到不存在并各自插入。应用层的“先查后写”提供业务语义，唯一索引负责并发兜底。

13. 为什么快照保存 JSON#

1
snapshot.setReportData(JSON.toJSONString(stats));

JSON 可以完整保留当时的汇总、趋势、平台占比和失败原因，读取历史报表时不需要按当前数据库重新计算。即使后来订单被修正，历史快照仍表达生成当时的统计结果。

代价是 JSON 内部字段不便直接做数据库查询，VO 结构升级也要考虑旧数据兼容。稳定的常用指标可以同时保存为独立列，完整展示结构继续保留 JSON。

14. 定时任务的日志与监控#

任务当前输出成功编号和处理数量。生产环境应使用日志框架替代 System.out.println，至少记录：

任务名称与调度时间；
实际统计区间；
生成或更新的报表编号；
处理数量和耗时；
失败异常与重试次数。

如果存在多实例部署，还要保证同一周期只有一个节点执行，或依靠数据库幂等与分布式锁共同控制。

15. 本篇小结#

统计接口的难点是口径，而不是 SQL 数量。统一时间窗口、补齐空时间段、处理零分母、区分实时数据和历史快照，再让定时任务保持幂等，报表才能长期稳定地被前端和运营使用。

实习笔记④

Wed, 22 Jul 2026 00:00:00 GMT

优化凭证查询模块。该模块需要展示一个会计期间内的凭证分录，并提供查看、复制和删除等操作。

后端列表接口返回的是“凭证分录”数据，同一张凭证会对应多条记录。例如凭证字号 0001 包含三条分录，接口会返回三行相同凭证字号的数据。因此，本周工作的重点不仅是调整页面样式，还包括将分录数据重新组织成凭证数据、合并表格行、设计独立查看页面，以及处理上一张和下一张凭证的切换。

经过几轮需求调整后，最终完成了以下内容：

相同“凭证字号”的公共列合并显示
操作列改为“查看”“复制”“删除”文字按钮
新增可复用的记账凭证展示组件
查看凭证由弹窗改为独立路由页面
复用原有列表接口，不新增后端详情接口
详情页支持上一张、下一张凭证切换
表格纵向、横向滚动条统一放在查询页面内部
取消操作列固定定位
配置“凭证查询 → 查看凭证”面包屑导航

1. 模块概述#

凭证查询模块位于 src/views/query/voucher 目录下，主要涉及以下文件：

文件	功能
`index.vue`	凭证查询列表页，负责条件查询、数据分组、行合并和操作入口
`detail.vue`	独立凭证查看页，负责详情展示和上一张、下一张切换
`components/VoucherSheet.vue`	记账凭证公共组件，同时支持查看模式和复制模式
`src/api/query/voucher.js`	凭证列表接口封装
`src/router/index.js`	查看凭证隐藏路由和面包屑配置

1.1 后端数据特点#

后端接口返回的数据结构如下：

1
{
2
  "total": 62,
3
  "code": 200,
4
  "msg": "查询成功",
5
  "rows": [
6
    {
7
      "account": "206009-其他代收代管款项",
8
      "d": 7482,
9
      "j": 0,
10
      "pzh": "0001",
11
      "pzrq": "2006-09-30",
12
      "zy": "代收电教费"
13
    },
14
    {
15
      "account": "206002-作业本款",
16
      "d": 1799.15,
17
      "j": 0,
18
      "pzh": "0001",
19
      "pzrq": "2006-09-30",
20
      "zy": "代收薄本款"
21
    },
22
    {
23
      "account": "102-银行存款",
24
      "d": 0,
25
      "j": 9281.15,
26
      "pzh": "0001",
27
      "pzrq": "2006-09-30",
28
      "zy": "代收薄本电教费"
29
    }
30
  ]
31
}

展开收起

从数据中可以看出：

pzh：凭证字号，同一张凭证的多条分录拥有相同的凭证字号
pzrq：凭证日期
zy：摘要
account：会计科目
j：借方金额
d：贷方金额

后端返回的 total 是分录数量，而页面需要按“凭证”进行展示和分页。因此，前端需要先按照 pzh 对分录进行分组，再计算实际的凭证数量。

1.2 最终页面流程#

1
index.vue（凭证查询列表）
2
    ↓ 调用 listVoucher
3
按 pzh 对 rows 分组
4
    ↓
5
表格合并公共列
6
    ↓ 点击“查看”
7
通过路由状态携带当前凭证列表
8
    ↓
9
detail.vue（查看凭证）
10
    ↓
11
点击左右箭头切换上一张/下一张

刷新详情页面时，路由状态可能不存在，因此增加了回退流程：

1
detail.vue 页面刷新
2
    ↓
3
读取路由中的单位、年度、期间和凭证字号
4
    ↓
5
再次调用 listVoucher
6
    ↓
7
按 pzh 分组并恢复凭证顺序
8
    ↓
9
定位当前凭证

2. 凭证查询列表页#

2.1 查询条件#

查询页面提供以下条件：

查询项	字段	说明
单位代码	`dwdm`	查询指定单位的数据
会计年度	`year`	查询指定年度
会计期间	`month`	查询指定月份
凭证字号	`pzh`	在前端分组结果中筛选凭证

查询参数初始化如下：

1
const defaultQuery = {
2
  pageNum: 1,
3
  pageSize: 10,
4
  dwdm: "1000",
5
  year: "2006",
6
  month: 9,
7
  pzh: ""
8
}
9

10
const queryParams = reactive({ ...defaultQuery })

列表接口仍然使用原有的 listVoucher：

1
export function listVoucher(query) {
2
  return request({
3
    url: '/voucher/list',
4
    method: 'get',
5
    params: query
6
  })
7
}

为了在前端完成凭证分组和分页，查询时一次获取当前期间的全部分录：

1
async function getList() {
2
  loading.value = true
3
  try {
4
    const response = await listVoucher({
5
      pageNum: 1,
6
      pageSize: 10000,
7
      dwdm: queryParams.dwdm,
8
      year: queryParams.year,
9
      month: queryParams.month
10
    })
11
    sourceRows.value = Array.isArray(response.rows) ? response.rows : []
12
    tableRef.value?.clearSelection()
13
  } finally {
14
    loading.value = false
15
  }
16
}

展开收起

2.2 按凭证字号分组#

接口返回的是分录数组，而列表页面的操作对象是一整张凭证。因此，使用 Map 按照 pzh 分组：

1
function buildGroups(rows) {
2
  const groupMap = new Map()
3

4
  rows.forEach((rawRow) => {
5
    const row = normalizeEntry(rawRow)
6
    const key = String(row.pzh)
7

8
    if (!groupMap.has(key)) {
9
      groupMap.set(key, {
10
        key,
11
        pzh: row.pzh,
12
        pzrq: row.pzrq,
13
        maker: firstValue(row, ["maker", "zdr", "creatorName", "createBy"]),
14
        reviewer: firstValue(row, ["reviewer", "shr", "reviewerName"]),
15
        bookkeeper: firstValue(row, ["bookkeeper", "jzr", "bookkeeperName"]),
16
        createTime: firstValue(row, ["createTime", "createdAt"]),
17
        attachmentCount: Number(
18
          firstValue(row, ["attachmentCount", "fjzs"], 0)
19
        ),
20
        entries: []
21
      })
22
    }
23

24
    groupMap.get(key).entries.push(row)
25
  })
26

27
  return Array.from(groupMap.values())
28
}

展开收起

分组后的数据结构如下：

1
{
2
  key: "0001",
3
  pzh: "0001",
4
  pzrq: "2006-09-30",
5
  maker: "—",
6
  reviewer: "—",
7
  bookkeeper: "—",
8
  attachmentCount: 0,
9
  entries: [
10
    {
11
      zy: "代收电教费",
12
      account: "206009-其他代收代管款项",
13
      j: 0,
14
      d: 7482
15
    },
16
    {
17
      zy: "代收薄本款",
18
      account: "206002-作业本款",
19
      j: 0,
20
      d: 1799.15
21
    },
22
    {
23
      zy: "代收薄本电教费",
24
      account: "102-银行存款",
25
      j: 9281.15,
26
      d: 0
27
    }
28
  ]
29
}

展开收起

通过这种结构，可以明确区分：

凭证级字段：凭证字号、凭证日期、制单人、审核人等
分录级字段：摘要、科目、借方金额、贷方金额

2.3 按凭证分页#

分组后使用计算属性进行凭证级分页：

1
const total = computed(() => availableGroups.value.length)
2

3
const pageGroups = computed(() => {
4
  const maxPage = Math.max(
5
    1,
6
    Math.ceil(total.value / queryParams.pageSize)
7
  )
8

9
  if (queryParams.pageNum > maxPage) {
10
    queryParams.pageNum = maxPage
11
  }
12

13
  const start = (queryParams.pageNum - 1) * queryParams.pageSize
14
  return availableGroups.value.slice(
15
    start,
16
    start + queryParams.pageSize
17
  )
18
})

展开收起

这样分页组件中的总数表示凭证数量，而不是后端返回的分录数量。

2.4 将凭证重新展开为表格行#

Element Plus 表格仍然需要逐行数据，因此将当前页的凭证重新展开，并增加用于行合并的辅助字段：

1
const tableRows = computed(() => {
2
  return pageGroups.value.flatMap((group) => {
3
    const groupSize = group.entries.length
4

5
    return group.entries.map((entry, index) => ({
6
      ...entry,
7
      _groupKey: group.key,
8
      _groupSize: groupSize,
9
      _groupOffset: index,
10
      _maker: group.maker,
11
      _reviewer: group.reviewer,
12
      _createTime: group.createTime
13
    }))
14
  })
15
})

展开收起

辅助字段	作用
`_groupKey`	标识当前行属于哪一张凭证
`_groupSize`	当前凭证包含多少条分录
`_groupOffset`	当前分录在凭证中的位置

3. 相同凭证字号合并行#

3.1 合并规则#

参考同类系统的展示方式，同一张凭证的以下列需要纵向合并：

勾选框
凭证日期
凭证字号
制单人
审核人
创建时间
操作

摘要、科目、借方金额和贷方金额仍然逐条显示，因为这些字段属于不同分录。

3.2 `span-method` 实现#

Element Plus 的 el-table 支持通过 span-method 返回每个单元格的行列合并信息：

1
function objectSpanMethod({ row, columnIndex }) {
2
  const mergedColumns = [0, 1, 2, 7, 8, 9, 10]
3

4
  if (!mergedColumns.includes(columnIndex)) {
5
    return {
6
      rowspan: 1,
7
      colspan: 1
8
    }
9
  }
10

11
  if (row._groupOffset === 0) {
12
    return {
13
      rowspan: row._groupSize,
14
      colspan: 1
15
    }
16
  }
17

18
  return {
19
    rowspan: 0,
20
    colspan: 0
21
  }
22
}

展开收起

实现思路：

判断当前列是否属于需要合并的公共列
如果是凭证第一条分录，rowspan 设置为分录数量
如果不是第一条分录，返回 rowspan: 0 隐藏重复单元格
摘要、科目和金额列始终返回普通单元格

3.3 整组勾选#

由于勾选框也进行了行合并，用户看到的是一张凭证对应一个勾选框。点击时需要同步选中该凭证的所有分录：

1
function handleGroupSelect(selection, row) {
2
  const selected = selection.some(
3
    (item) => getRowKey(item) === getRowKey(row)
4
  )
5

6
  tableRows.value
7
    .filter((item) => item._groupKey === row._groupKey)
8
    .forEach((item) => {
9
      tableRef.value?.toggleRowSelection(item, selected)
10
    })
11
}

优化后凭证列表

4. 操作列优化#

4.1 从图标改为文字按钮#

原页面的操作列只显示一个编辑图标，操作含义不够直观。优化后在单元格中直接显示三个文字按钮：

1
<div class="operation-buttons">
2
  <el-button link type="primary" @click="handleView(row)">
3
    查看
4
  </el-button>
5
  <el-button link type="warning" @click="handleCopy(row)">
6
    复制
7
  </el-button>
8
  <el-button link type="danger" @click="handleDelete(row)">
9
    删除
10
  </el-button>
11
</div>

按钮	颜色	功能
查看	蓝色	跳转到独立查看凭证页面
复制	橙色	打开复制凭证编辑界面
删除	红色	确认后从当前列表移除凭证

4.2 取消操作列固定#

最初操作列使用了：

1
fixed="right"

当表格产生横向滚动时，固定列会覆盖部分内容，并且与参考页面的行为不一致。因此删除固定属性，让操作列和其他列一起参与横向滚动。

最终配置如下：

1
<el-table-column
2
  label="操作"
3
  width="208"
4
  align="center"
5
  class-name="voucher-operation-column"
6
>

5. 页面滚动区域优化#

5.1 问题现象#

优化前，整个后台内容区域会出现纵向滚动条，表格本身只有横向滚动条，导致：

页面标题、查询条件和分页会一起上下滚动
外层页面和表格的滚动行为不统一
页面底部容易被版权区域遮挡
固定操作列与滚动内容的视觉关系不自然

5.2 外层页面固定#

将凭证查询页设置为纵向 Flex 布局，并禁止外层滚动：

1
.voucher-query-page {
2
  --voucher-border-color: #e5e7eb;
3
  display: flex;
4
  flex-direction: column;
5
  height: 100%;
6
  min-height: 0;
7
  overflow: hidden;
8
  background: #f5f7fa;
9
}

5.3 表格区域内部滚动#

表格卡片占用查询条件之外的剩余空间：

1
.table-card {
2
  display: flex;
3
  flex: 1 1 auto;
4
  flex-direction: column;
5
  min-height: 0;
6

7
  :deep(.el-card__body) {
8
    display: flex;
9
    flex: 1 1 auto;
10
    flex-direction: column;
11
    min-height: 0;
12
    padding: 0;
13
  }
14
}

表格外增加单独的自适应容器：

1
.voucher-table-wrapper {
2
  flex: 1 1 auto;
3
  min-height: 0;
4
}
5

6
.voucher-table {
7
  width: 100%;
8
  height: 100%;
9
}

同时为 el-table 设置：

1
<el-table
2
  height="100%"
3
  class="voucher-table"
4
>

这样：

纵向滚动条位于表格内容区域右侧
横向滚动条位于表格内容区域底部
查询条件和分页保持在页面固定位置
外层后台页面不再产生额外滚动条

图片占位：表格内部纵向和横向滚动条效果

表格内部滚动效果（待补充）

6. 记账凭证公共组件#

为了同时支持查看凭证和复制凭证，新增了 VoucherSheet.vue 公共组件。

6.1 组件属性#

1
const props = defineProps({
2
  voucher: {
3
    type: Object,
4
    required: true
5
  },
6
  mode: {
7
    type: String,
8
    default: "view",
9
    validator: (value) => ["view", "copy"].includes(value)
10
  },
11
  canPrevious: {
12
    type: Boolean,
13
    default: false
14
  },
15
  canNext: {
16
    type: Boolean,
17
    default: false
18
  },
19
  showNavigation: {
20
    type: Boolean,
21
    default: true
22
  }
23
})

展开收起

属性	说明
`voucher`	当前凭证数据
`mode`	`view` 为只读查看，`copy` 为复制编辑
`canPrevious`	是否允许切换上一张
`canNext`	是否允许切换下一张
`showNavigation`	是否在凭证组件内部显示导航按钮

6.2 查看模式与复制模式#

通过计算属性判断组件模式：

1
const isCopyMode = computed(() => props.mode === "copy")

查看模式下：

凭证字号只读
凭证日期只读
摘要和科目以文字展示
借贷金额按金额位数表格展示

复制模式下：

可以修改凭证字号和日期
可以编辑摘要、科目和借贷金额
可以新增或移除分录
可以保存副本到当前列表

6.3 金额位数展示#

参考会计凭证样式，金额区域划分为：

1
const moneyLabels = [
2
  "亿", "千", "百", "十",
3
  "万", "千", "百", "十",
4
  "元", "角", "分"
5
]

金额转换函数：

1
function moneyDigits(value) {
2
  const amount = Number(value || 0)
3
  if (!amount) {
4
    return Array(11).fill("")
5
  }
6

7
  const cents = Math.round(amount * 100)
8
  return String(cents)
9
    .slice(-11)
10
    .padStart(11, " ")
11
    .split("")
12
    .map((digit) => digit.trim())
13
}

这样可以将 9281.15 拆分到“千、百、十、元、角、分”对应的格子中，更接近纸质记账凭证。

6.4 借贷合计#

1
const debitTotal = computed(() =>
2
  form.entries.reduce(
3
    (total, entry) => total + Number(entry.j || 0),
4
    0
5
  )
6
)
7

8
const creditTotal = computed(() =>
9
  form.entries.reduce(
10
    (total, entry) => total + Number(entry.d || 0),
11
    0
12
  )
13
)

复制保存前需要验证借贷金额是否平衡：

1
if (Math.abs(debitTotal - creditTotal) > 0.005) {
2
  proxy.$modal.msgWarning("借贷金额不平衡，请核对后再保存")
3
  return
4
}

图片占位：查看凭证页面

查看凭证页面（待补充）

图片占位：复制凭证页面

复制凭证页面（待补充）

7. 查看凭证独立路由#

7.1 从弹窗改为独立页面#

第一版查看凭证使用 el-dialog 弹窗。后续需求要求取消弹窗，改为路由跳转并配置面包屑。

独立页面的优点：

查看凭证拥有完整页面空间
浏览器地址可以表示当前凭证
页面刷新后可以重新恢复数据
面包屑和标签页可以显示当前所在位置
更适合后续增加打印、附件等功能

7.2 路由配置#

新增隐藏路由：

1
{
2
  path: '/voucher-detail',
3
  component: Layout,
4
  hidden: true,
5
  redirect: '/query/voucher',
6
  meta: {
7
    title: '凭证查询'
8
  },
9
  children: [
10
    {
11
      path: ':pzh',
12
      component: () => import('@/views/query/voucher/detail'),
13
      name: 'VoucherDetail',
14
      meta: {
15
        title: '查看凭证',
16
        activeMenu: '/query/voucher',
17
        noCache: true
18
      }
19
    }
20
  ]
21
}

展开收起

配置说明：

配置项	作用
`hidden: true`	不在侧边栏中增加新的菜单
`:pzh`	使用凭证字号作为路由参数
`title: 查看凭证`	设置标签页和面包屑标题
`activeMenu`	查看详情时仍高亮“凭证查询”菜单
`noCache`	切换凭证时使用最新路由数据

最终面包屑为：

1
首页 / 凭证查询 / 查看凭证

其中“凭证查询”可以返回列表页面。

7.3 为什么使用凭证字号#

最初计划通过凭证 ID 请求详情，但实际列表接口返回的数据中没有独立的凭证 ID，只有：

pzh
pzrq
zy
account
j
d

同一期间内，pzh 可以标识一张凭证，因此最终使用凭证字号作为路由参数：

1
/voucher-detail/0001

这避免了为了详情页额外修改后端接口。

8. 复用列表数据实现详情跳转#

8.1 跳转时传递查询上下文#

点击查看时，路由参数携带凭证字号，查询参数携带单位、年度和期间：

1
function handleView(row) {
2
  const group = groupFromRow(row)
3
  if (!group) return
4

5
  router.push({
6
    name: "VoucherDetail",
7
    params: {
8
      pzh: group.pzh
9
    },
10
    query: {
11
      dwdm: queryParams.dwdm,
12
      year: queryParams.year,
13
      month: queryParams.month
14
    },
15
    state: {
16
      vouchers: cloneGroup(availableGroups.value)
17
    }
18
  })
19
}

展开收起

路由中各部分的作用：

数据	作用
`params.pzh`	标识当前查看的凭证
`query.dwdm`	页面刷新时重新查询单位数据
`query.year`	页面刷新时重新查询年度数据
`query.month`	页面刷新时重新查询期间数据
`state.vouchers`	正常跳转时直接复用列表页已经整理好的凭证数据

8.2 优先使用路由状态#

正常从列表页进入详情页时，可以直接从浏览器历史状态中读取凭证列表：

1
function voucherListFromRouteState() {
2
  const stateList = window.history.state?.vouchers
3

4
  if (!Array.isArray(stateList) || !stateList.length) {
5
    return []
6
  }
7

8
  return stateList.map(normalizeVoucher)
9
}

这样点击查看时不会重复请求接口，页面可以立即显示。

8.3 刷新页面时回退到列表接口#

如果用户刷新页面，路由状态可能不存在。这时根据路由中的查询条件重新调用 listVoucher：

1
const response = await listVoucher({
2
  pageNum: 1,
3
  pageSize: 10000,
4
  dwdm,
5
  year,
6
  month
7
})
8

9
const rows = Array.isArray(response.rows)
10
  ? response.rows
11
  : []
12

13
voucherList.value = buildVoucherList(rows)
14
selectVoucher(pzh)

这种设计兼顾了两种场景：

正常跳转：复用列表数据，不重复请求
页面刷新：复用原列表接口，恢复详情数据

9. 上一张和下一张凭证#

9.1 当前凭证索引#

详情页保存完整的凭证列表，并根据路由中的 pzh 计算当前索引：

1
const currentIndex = computed(() =>
2
  voucherList.value.findIndex(
3
    (item) =>
4
      String(item.pzh) === String(route.params.pzh)
5
  )
6
)

9.2 按钮禁用状态#

1
const canPrevious = computed(
2
  () => currentIndex.value > 0
3
)
4

5
const canNext = computed(
6
  () =>
7
    currentIndex.value >= 0 &&
8
    currentIndex.value < voucherList.value.length - 1
9
)

规则如下：

当前是第一张凭证：禁用左箭头
当前是最后一张凭证：禁用右箭头
中间凭证：左右箭头都可以点击

9.3 切换凭证#

1
function showAdjacentVoucher(step) {
2
  const target =
3
    voucherList.value[currentIndex.value + step]
4

5
  if (!target) return
6

7
  router.replace({
8
    name: "VoucherDetail",
9
    params: {
10
      pzh: target.pzh
11
    },
12
    query: route.query,
13
    state: {
14
      vouchers: JSON.parse(
15
        JSON.stringify(voucherList.value)
16
      )
17
    }
18
  })
19
}

展开收起

这里使用 router.replace，而不是 router.push：

replace 会更新当前详情地址
不会为每一次左右切换增加新的浏览历史
浏览器返回时可以直接回到凭证查询页

按钮模板：

1
<div class="detail-navigation">
2
  <el-button
3
    icon="ArrowLeft"
4
    :disabled="!canPrevious"
5
    title="上一张凭证"
6
    @click="showAdjacentVoucher(-1)"
7
  />
8
  <el-button
9
    icon="ArrowRight"
10
    :disabled="!canNext"
11
    title="下一张凭证"
12
    @click="showAdjacentVoucher(1)"
13
  />
14
</div>

10. 复制凭证#

复制凭证继续使用弹窗，因为复制过程属于临时编辑操作，不需要生成新的详情路由。

10.1 生成新凭证字号#

1
function incrementVoucherNumber(currentNumber) {
2
  const match = String(currentNumber || "")
3
    .match(/^(.*?)(\d+)$/)
4

5
  const prefix = match?.[1] || ""
6
  const width = match?.[2]?.length || 4
7

8
  const matchingNumbers = availableGroups.value
9
    .map((group) =>
10
      String(group.pzh).match(/^(.*?)(\d+)$/)
11
    )
12
    .filter(
13
      (item) => item && item[1] === prefix
14
    )
15
    .map((item) => Number(item[2]))
16

17
  const nextNumber =
18
    Math.max(
19
      Number(match?.[2] || 0),
20
      ...matchingNumbers,
21
      0
22
    ) + 1
23

24
  return `${prefix}${String(nextNumber).padStart(
25
    width,
26
    "0"
27
  )}`
28
}

展开收起

例如：

1
当前凭证字号：0009
2
复制后凭证字号：0010

10.2 复制数据#

1
function handleCopy(row) {
2
  const group = groupFromRow(row)
3
  if (!group) return
4

5
  const copy = cloneGroup(group)
6
  copy.pzh = incrementVoucherNumber(group.pzh)
7
  copy.key = copy.pzh
8
  copy.reviewer = "—"
9
  copy.bookkeeper = "—"
10

11
  copy.entries = copy.entries.map((entry) => ({
12
    ...entry,
13
    pzh: copy.pzh
14
  }))
15

16
  copyVoucher.value = copy
17
  copyVisible.value = true
18
}

展开收起

10.3 保存前校验#

保存副本前检查：

凭证字号不能为空
至少保留一条有效分录
新凭证字号不能重复
借方金额和贷方金额必须平衡

这些校验可以避免在当前列表中产生明显错误的凭证数据。

这一周把一条条凭证分录整理成了一张张可以查看、复制和切换的凭证，感觉自己对前端数据建模和路由状态的理解又深入了一些。

后端开发日记⑧：站内消息与微信订阅额度

Sun, 19 Jul 2026 00:00:00 GMT

订单状态改变以后，用户既需要在消息中心看到记录，也希望收到微信订阅消息。两种渠道作用不同：站内消息保存业务事实，微信消息负责把用户从应用外叫回来。

1. 站内消息按当前用户隔离#

用户消息列表接口仍然使用通用分页结构，但查询条件由 Service 补充：

1
HyNotification query = request == null
2
        ? new HyNotification() : request;
3
query.setWxUserId(SecurityUtils.getUserId());
4
return notificationMapper.selectHyNotificationList(query);

前端可以筛选已读状态或通知类型，却不能查询其他用户 ID。把身份条件放在 Service 中，可以防止 Controller 新增入口时忘记隔离。

2. 为什么要记录订阅额度#

微信一次性订阅消息需要用户主动允许。前端获得授权结果后，把模板 ID 和允许次数上报后端，后端按“用户 + 模板”保存可用额度。

额度记录至少包含：

availableCount：还可发送多少次；
usedCount：已经使用多少次；
用户 ID 与模板 ID 联合定位一条记录。

同一模板再次授权时增加额度，而不是覆盖已有计数。

3. 发送前预扣#

如果先调用微信、成功后再减额度，两个并发发送都可能看到余额为 1，最后发送两次。项目把顺序改为：

1
原子扣减 availableCount
2
  -> 调用微信订阅消息接口
3
  -> 成功：保留 usedCount
4
  -> 失败：恢复刚才预扣的额度

Mapper 的 consumeAvailableCount 在 SQL 条件中要求可用数大于 0，并同时完成减一与已用数加一。是否扣减成功由受影响行数判断。

4. 失败恢复不是无限重试#

网络异常或微信响应失败时，服务恢复额度，并记录发送失败结果。恢复解决的是“用户授权不能被白白消耗”，不代表应该在当前请求里无限重试。

对于明确的 Token 失效，可以刷新 Token 后重试一次；对于模板参数错误、用户拒收等业务错误，应保留失败状态供排查。

5. 双通道如何协作#

订单审核、开始飞行、送达或异常处理完成时，业务 Service 可以先写站内通知，再尝试发送微信订阅消息：

通道	特点	失败后的处理
站内消息	可查询、可分页、可保留历史	属于业务数据，应随事务处理
微信订阅消息	到达应用外、依赖用户授权和第三方平台	记录结果并恢复额度，不应破坏已完成业务

是否让外部推送失败回滚订单，需要按业务风险决定。通常订单状态是主事实，推送失败应进入补偿或重试，而不是把已经完成的配送改回原状态。

6. 授权上报如何限制客户端计数#

用户端上报订阅授权时，后端把单次最大数量限制为 1：

1
Integer count = reportDto.getCount();
2
if (count == null || count <= 0) {
3
    count = 1;
4
}
5
if (count > MAX_REPORT_COUNT) {
6
    count = MAX_REPORT_COUNT;
7
}

这是因为客户端提交的 count 不是可信余额。前端一次授权成功只能证明获得了本次允许，不能随意提交 100 增加额度。

接着按当前用户和模板查询：

1
Long wxUserId = SecurityUtils.getUserId();
2
HyWxSubscribeQuota quota = mapper
3
        .selectByWxUserIdAndTemplateId(
4
                wxUserId, templateId);
5
if (quota == null) {
6
    // 初始化 availableCount、acceptCount、usedCount
7
    mapper.insertHyWxSubscribeQuota(quota);
8
} else {
9
    mapper.increaseQuota(wxUserId, templateId, count);
10
}

用户 ID 来自安全上下文，模板 ID 来自允许上报的业务参数。生产环境还可以增加模板白名单，阻止用户为系统未知模板创建额度记录。

7. 原子扣减为什么写在 SQL 中#

1
<update id="consumeAvailableCount">
2
    update hy_wx_subscribe_quota
3
    set available_count = available_count - 1,
4
        used_count = used_count + 1,
5
        update_time = now()
6
    where wx_user_id = #{wxUserId}
7
      and template_id = #{templateId}
8
      and available_count &gt; 0
9
</update>

判断余额和扣减发生在一条 SQL 中。两个并发请求即使同时到达，数据库也会串行修改同一行：第一个把 1 改成 0，第二个执行时条件 available_count > 0 已不成立，受影响行数为 0。

如果先 SELECT 再 UPDATE，两次查询可能都读到 1，最后发送两条消息。数据库条件更新比 Java 中的普通 if 更接近真正的数据竞争位置。

8. 发送方法的完整分支#

1
HyNotification notification =
2
        buildPendingWechatNotification(order);
3
notificationMapper.insertHyNotification(notification);
4

5
int rows = quotaMapper.consumeAvailableCount(
6
        order.getWxUserId(), templateId);
7
if (rows <= 0) {
8
    markNotificationFailed(
9
            notification, "用户未订阅或订阅额度已用完");
10
    return;
11
}
12

13
try {
14
    HyWxUser user = userMapper.selectById(order.getWxUserId());
15
    JsonNode result = sendSubscribeMessage(user.getOpenId(), order);
16
    if (result.path("errcode").asInt(-1) != 0) {
17
        throw new ServiceException("微信返回失败");
18
    }
19
    markNotificationSuccess(notification);
20
} catch (Exception e) {
21
    quotaMapper.restoreConsumedCount(
22
            order.getWxUserId(), templateId);
23
    markNotificationFailed(notification, e.getMessage());
24
}

展开收起

第一步就创建 PENDING 通知，保证无论后续在哪个位置失败都有记录。没有额度时直接标记失败；有额度才访问用户 openid 和微信接口。

成功后设置 SUCCESS 与发送时间，异常时恢复额度并保存失败原因。日志可以看到订单、用户和失败阶段，而不是只得到一个“推送没有到达”的投诉。

9. 恢复额度为什么保护 used_count#

1
<update id="restoreConsumedCount">
2
    update hy_wx_subscribe_quota
3
    set available_count = available_count + 1,
4
        used_count = case
5
            when used_count &gt; 0 then used_count - 1
6
            else 0
7
        end,
8
        update_time = now()
9
    where wx_user_id = #{wxUserId}
10
      and template_id = #{templateId}
11
</update>

case 保证异常数据下 used_count 不会被减成负数。但恢复操作本身也需要幂等标识：如果同一个失败被处理两次，available_count 会多加一次。

更严格的设计可以给每次发送建立唯一消息 ID，并在通知表记录是否已经恢复额度；只有从“已预扣”首次转为“发送失败”时执行恢复。

10. 模板 data 为什么要限制长度#

1
private ObjectNode buildSubscribeData(HyDeliveryOrder order) {
2
    ObjectNode data = objectMapper.createObjectNode();
3
    data.set("character_string1", valueNode(limit(
4
            defaultString(order.getOrderNo()), 32)));
5
    data.set("thing3", valueNode(limit(
6
            getPickupAddress(order), 20)));
7
    data.set("time14", valueNode(
8
            DateUtils.parseDateToStr(
9
                    DateUtils.YYYY_MM_DD_HH_MM_SS,
10
                    DateUtils.getNowDate())));
11
    return data;
12
}

微信模板字段不仅有名称，还有类型与长度限制。订单号使用 character_string，取货点使用 thing，时间使用 time。直接把长地址塞入 thing3 会被微信拒绝，所以在发送前按字段类型截断。

字段名 character_string1、thing3、time14 必须与后台模板配置完全一致。模板变更时最好把字段映射集中管理，并通过测试请求尽早发现不匹配。

11. 跳转页面也属于消息契约#

发送体中包含：

1
body.put("page",
2
        "pages/order/detail?orderId=" + order.getOrderId());
3
body.put("miniprogram_state", miniprogramState);
4
body.put("lang", "zh_CN");

消息虽然发送成功，但页面路径错误仍会导致用户点击后无法到达订单。后端与小程序需要共同维护路径契约，订单 ID 也要在目标页再次经过当前用户归属校验。

miniprogram_state 可以区分开发版、体验版和正式版，应该通过环境配置而不是在代码中临时修改。

12. 事务与外部请求的边界#

发送方法带有数据库事务，但微信请求不会参与数据库回滚。如果微信已经收到消息，随后本地更新通知状态失败，事务回滚额度后可能让系统误以为可以再次发送。

更可靠的演进方案是事务消息表：

1
订单事务内写入待发送事件
2
  -> 事务提交
3
  -> 独立发送器领取事件并预扣额度
4
  -> 调用微信
5
  -> 保存成功或失败
6
  -> 超时任务重试可重试错误

这样订单完成接口不必等待外部网络，也能通过事件 ID 控制幂等。当前同步方案适合规模较小的阶段，但需要清楚它的边界。

13. 本篇小结#

消息系统不能只关注“发送接口返回成功”。站内消息负责可追溯，订阅额度负责发送资格，原子预扣负责并发正确性，失败恢复负责不浪费授权。把这些角色分开，通知链路才具备可解释的失败处理。

实习笔记③

Fri, 17 Jul 2026 00:00:00 GMT

开发留言板处理模块，该模块位于 src/views/message-board/handle 目录下，包含留言列表展示、留言答复、留言查看、公开状态切换等功能。

1. 模块概述#

留言板处理模块用于管理和处理用户提交的留言信息，主要功能包括：

功能	说明
留言列表展示	展示所有留言，支持按标题、时间、办理状态筛选
留言查看	查看留言详细信息，包括留言内容、附件、答复内容
留言答复	对未答复的留言进行答复，支持首次答复和二次答复
公开状态切换	通过开关控制留言是否公开显示
附件下载	支持下载留言附件（图片、PDF、其他文件）

文件结构#

1
handle/
2
├── data.ts          # 表格列配置和查询表单配置
3
├── index.vue        # 留言列表页
4
├── form.vue         # 留言答复/查看页
5
└── message-board/
6
    └── index.ts     # API 接口定义

页面流程#

1
index.vue（留言列表）
2
    ↓ 点击"答复"按钮
3
form.vue（留言答复）
4
    ↓ 提交答复后返回
5
index.vue（留言列表刷新）
6

7
index.vue（留言列表）
8
    ↓ 点击"查看"按钮
9
form.vue（留言查看）

2. data.ts（表格配置）#

2.1 办理状态选项#

1
const statusOptions = reactive([
2
  { label: '全部', value: '' },
3
  { label: '已答复', value: '1' },
4
  { label: '待答复', value: '0' },
5
]);

值	标签	说明
`''`	全部	查询所有状态的留言
`'1'`	已答复	查询已处理的留言
`'0'`	待答复	查询未处理的留言

使用 reactive 定义响应式状态选项数组，供查询表单的下拉选择器使用。

2.2 查询表单配置#

1
export const querySchema: FormSchemaGetter = () => [
2
  {
3
    component: 'Input',
4
    fieldName: 'noticeTitle',
5
    label: '留言标题',
6
  },
7
  {
8
    component: 'RangePicker',
9
    fieldName: 'noticeTime',
10
    label: '留言时间',
11
  },
12
  {
13
    component: 'Select',
14
    fieldName: 'handleStatus',
15
    label: '办理状态',
16
    defaultValue: '',
17
    componentProps: {
18
      getPopupContainer,
19
      options: statusOptions,
20
    },
21
  },
22
];

展开收起

字段	组件	说明
`noticeTitle`	`Input`	留言标题，支持模糊搜索
`noticeTime`	`RangePicker`	留言时间范围选择器
`handleStatus`	`Select`	办理状态下拉选择

关键配置说明：

getPopupContainer：用于设置下拉菜单的挂载容器，解决弹窗被遮挡的问题
defaultValue: ''：办理状态默认选中”全部”

2.3 表格列配置#

1
export const columns: VxeGridProps['columns'] = [
2
  {
3
    title: '留言标题',
4
    field: 'noticeTitle',
5
    align: 'left',
6
  },
7
  {
8
    title: '是否公开',
9
    field: 'isPublic',
10
    align: 'center',
11
    width: 100,
12
    slots: {
13
      default: 'isPublic',
14
    },
15
  },
16
  {
17
    title: '留言时间',
18
    field: 'noticeTime',
19
    align: 'left',
20
    width: 200,
21
  },
22
  {
23
    title: '办理状态',
24
    field: 'handleStatus',
25
    align: 'left',
26
    width: 100,
27
    slots: {
28
      default: ({ row }) => {
29
        if (row.handleStatus == '1') {
30
          return '已答复';
31
        } else {
32
          return '待答复';
33
        }
34
      },
35
    },
36
  },
37
  {
38
    field: 'action',
39
    fixed: 'right',
40
    width: 'auto',
41
    align: 'left',
42
    slots: { default: 'action' },
43
    title: '操作',
44
    resizable: false,
45
  },
46
];

展开收起

列	字段	宽度	说明
留言标题	`noticeTitle`	自适应	显示留言标题
是否公开	`isPublic`	100px	通过插槽渲染开关组件
留言时间	`noticeTime`	200px	显示留言提交时间
办理状态	`handleStatus`	100px	通过插槽渲染中文标签
操作	`action`	自适应	固定在右侧，包含查看/答复按钮

关键技术点：

插槽机制：slots.default 用于自定义单元格渲染内容
- isPublic 列使用 default: 'isPublic'，在模板中通过 <template #isPublic> 自定义渲染
- handleStatus 列使用函数形式，根据状态值返回不同文本
状态值转换：handleStatus 字段存储的是数字字符串（'0' 或 '1'），通过函数转换为中文标签显示
操作列固定：fixed: 'right' 确保操作列始终显示在表格右侧，方便用户操作

3. index.vue（留言列表页）#

3.1 页面功能#

展示留言列表，支持：

按留言标题、留言时间、办理状态筛选
分页展示
查看已答复留言详情
答复未处理留言
切换留言公开状态

3.2 代码实现#

导入模块

1
import type { VbenFormProps } from '@vben/common-ui';
2
import type { VxeGridProps } from '#/adapter/vxe-table';
3
import { Page } from '@vben/common-ui';
4
import { message } from 'ant-design-vue';
5
import { Space, Modal } from 'ant-design-vue';
6
import { getVxePopupContainer } from '@vben/utils';
7
import { useVbenVxeGrid } from '#/adapter/vxe-table';
8
import { columns, querySchema } from './data';
9
import { useRouter } from 'vue-router';
10
import { noticeBoardList, updatePublic } from '#/api/business/message-board/index';
11
import { onActivated } from 'vue';

导入项	说明
`VbenFormProps`	Vben 表单组件属性类型定义
`VxeGridProps`	Vxe 表格组件属性类型定义
`Page`	Vben 页面布局组件
`message`	Ant Design Vue 消息提示组件
`Modal`	Ant Design Vue 模态框组件
`useVbenVxeGrid`	封装 Vxe 表格和查询表单的组合式函数
`columns`	表格列配置（来自 data.ts）
`querySchema`	查询表单配置（来自 data.ts）
`noticeBoardList`	获取留言列表 API
`updatePublic`	更新留言公开状态 API
`onActivated`	组件从缓存中激活时触发的生命周期钩子

表单配置

1
const formOptions: VbenFormProps = {
2
  commonConfig: {
3
    labelWidth: 80,
4
    componentProps: {
5
      allowClear: true,
6
    },
7
  },
8
  schema: querySchema(),
9
  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4',
10
  fieldMappingTime: [
11
    [
12
      'noticeTime',
13
      ['params[beginTime]', 'params[endTime]'],
14
      ['YYYY-MM-DD 00:00:00', 'YYYY-MM-DD 23:59:59'],
15
    ],
16
  ],
17
};

展开收起

配置项	作用
`labelWidth`	表单标签宽度，设置为 80px
`allowClear`	表单组件支持一键清空
`schema`	查询表单字段定义，调用 `querySchema()` 获取
`wrapperClass`	表单网格布局样式类，响应式显示 1-4 列
`fieldMappingTime`	日期范围选择器字段映射，将 `noticeTime` 转换为 `beginTime` 和 `endTime`

日期字段映射详解：

fieldMappingTime 配置将前端的 noticeTime（日期范围选择器值）自动转换为后端需要的两个参数：

params[beginTime]：开始时间，格式为 YYYY-MM-DD 00:00:00
params[endTime]：结束时间，格式为 YYYY-MM-DD 23:59:59

这样前端只需要处理一个日期范围字段，后端接收到的是两个独立的时间参数。

表格配置

1
const gridOptions: VxeGridProps = {
2
  border: true,
3
  checkboxConfig: {
4
    highlight: true,
5
    reserve: true,
6
  },
7
  columns,
8
  height: 'auto',
9
  keepSource: true,
10
  pagerConfig: {},
11
  proxyConfig: {
12
    ajax: {
13
      query: async ({ page }, formValues = {}) => {
14
        return await noticeBoardList({
15
          pageNum: page.currentPage,
16
          pageSize: page.pageSize,
17
          ...formValues,
18
        });
19
      },
20
    },
21
  },
22
  rowConfig: {
23
    keyField: 'id',
24
  },
25
  id: 'massage-board-handle-index',
26
};

展开收起

配置项	作用
`border`	显示表格边框
`checkboxConfig.highlight`	选中行高亮显示
`checkboxConfig.reserve`	翻页时保留选中状态
`height: 'auto'`	表格高度自适应内容
`keepSource`	保留原始数据，用于数据对比
`pagerConfig`	分页配置，使用默认配置
`proxyConfig.ajax.query`	数据代理查询函数，自动处理分页参数
`rowConfig.keyField`	行唯一标识字段，设置为 `id`
`id`	表格唯一标识，用于表格 API 操作

数据代理查询详解：

proxyConfig.ajax.query 是 Vxe 表格的数据代理配置，其工作原理如下：

表格组件自动监听分页变化、查询条件变化
当需要获取数据时，调用 query 函数
query 函数接收两个参数：
- { page }：分页信息，包含 currentPage（当前页码）和 pageSize（每页条数）
- formValues：查询表单的值
将分页参数和表单参数合并后调用 noticeBoardList API
API 返回的数据自动填充到表格中

这种方式将分页逻辑和数据获取逻辑解耦，表格组件自动处理分页状态管理。

创建表格实例

1
const [BasicTable, tableApi] = useVbenVxeGrid({
2
  formOptions,
3
  gridOptions,
4
} as any);

useVbenVxeGrid 是一个组合式函数，返回两个值：

BasicTable：表格组件，用于模板渲染
tableApi：表格操作 API，用于执行查询、刷新等操作

答复留言方法

1
function handleReply(row: any) {
2
  router.push({
3
    path: './form',
4
    query: {
5
      id: row.id,
6
      type: 'reply',
7
    },
8
  });
9
}

跳转到表单页，标记为答复模式
通过 query 参数传递留言 ID 和操作类型

查看留言方法

1
function handleView(row: any) {
2
  router.push({
3
    path: './form',
4
    query: {
5
      id: row.id,
6
      type: 'view',
7
    },
8
  });
9
}

跳转到表单页，标记为查看模式
通过 query 参数传递留言 ID 和操作类型

公开状态切换方法（核心功能）

1
interface MessageBoardRow {
2
  id: string;
3
  isPublic: string;
4
}
5

6
async function handlePublicChange(row: MessageBoardRow, checked: boolean) {
7
  Modal.confirm({
8
    title: '提示',
9
    content: '确认要修改吗？',
10
    onOk: async () => {
11
      try {
12
        await updatePublic({
13
          id: row.id,
14
          isPublic: checked ? '1' : '0',
15
        });
16
        row.isPublic = checked ? '1' : '0';
17
        message.success(checked ? '已设为公开' : '已设为不公开');
18
      } catch {
19
        message.error('操作失败');
20
      }
21
    },
22
  });
23
}

展开收起

方法详解：

类型定义：MessageBoardRow 接口定义了行数据的类型，包含 id 和 isPublic 字段
确认弹窗：使用 Modal.confirm 弹出确认对话框，防止误操作
API 调用：调用 updatePublic API 更新公开状态
- isPublic: '1'：设为公开
- isPublic: '0'：设为不公开
本地状态更新：API 调用成功后，直接更新 row.isPublic 的值，实现即时反馈
消息提示：根据操作结果显示成功或失败提示

列表刷新机制

1
onActivated(() => {
2
  tableApi.query();
3
});

当组件从缓存中激活时（如从表单页返回），自动调用 tableApi.query() 刷新列表数据，确保显示最新内容。

3.3 模板结构#

1
<template>
2
  <Page :auto-content-height="true">
3
    <BasicTable table-title="留言列表">
4
      <template #isPublic="{ row }">
5
        <a-switch :checked="row.isPublic === '1'" @change="(checked) => handlePublicChange(row, checked)" />
6
      </template>
7
      <template #action="{ row }">
8
        <Space>
9
          <Space v-if="row.handleStatus == '1'">
10
            <ghost-button @click.stop="handleView(row)"> 查看</ghost-button>
11
          </Space>
12
          <ghost-button @click.stop="handleReply(row)" v-else>
13
            答复</ghost-button>
14
        </Space>
15
      </template>
16
    </BasicTable>
17
  </Page>
18
</template>

展开收起

模板部分	作用
`#isPublic`	自定义”是否公开”列的渲染，使用 `a-switch` 开关组件
`#action`	自定义操作列的渲染，根据办理状态显示不同按钮
`v-if="row.handleStatus == '1'"`	已答复状态显示”查看”按钮
`v-else`	待答复状态显示”答复”按钮

开关组件使用：

1
<a-switch :checked="row.isPublic === '1'" @change="(checked) => handlePublicChange(row, checked)" />

:checked：绑定开关状态，row.isPublic === '1' 时为开启状态
@change：开关状态变化时触发 handlePublicChange 方法

4. form.vue（留言答复/查看页）#

4.1 页面功能#

留言详情页，支持：

查看留言详细信息（时间、类型、答复单位、姓名、联系方式、标题、内容）
查看留言附件（图片预览、PDF预览、文件下载）
查看首次答复内容和二次答复内容
对未答复留言进行首次答复
对已有答复的留言进行修改或撤销
对二次反馈进行答复、修改或撤销

4.2 代码实现#

导入模块

1
import { Page } from '@vben/common-ui';
2
import { useTabs } from '@vben/hooks';
3
import { checkLoginBeforeDownload } from '#/api/system/oss';
4
import { useRouter, useRoute } from 'vue-router';
5
import { onMounted, reactive, ref } from 'vue';
6
import {
7
  queryByMessageBoardById,
8
  reply,
9
  replySecond,
10
  revoke,
11
  revokeSecond,
12
  fileData,
13
} from '#/api/business/message-board/index';
14
import { useAppConfig } from '@vben/hooks';
15
import { useAccessStore } from '@vben/stores';
16
import { stringify } from '@vben/request';
17
import { downloadByUrl } from '#/utils/file/download';

展开收起

导入项	说明
`useTabs`	Vben 标签页管理钩子，用于关闭当前标签页
`checkLoginBeforeDownload`	文件下载前登录检查
`queryByMessageBoardById`	根据 ID 查询留言详情 API
`reply`	首次答复 API
`replySecond`	二次答复 API
`revoke`	撤销首次答复 API
`revokeSecond`	撤销二次答复 API
`fileData`	获取附件列表 API
`useAppConfig`	获取应用配置（API URL、客户端 ID）
`useAccessStore`	获取访问令牌
`downloadByUrl`	文件下载工具函数

响应式数据定义

1
const router = useRouter();
2
const route = useRoute();
3
const { closeCurrentTab, setTabTitle } = useTabs();
4

5
const formData = reactive<any>({
6
  replyContent: '',
7
});
8

9
const typeOptions = ref([
10
  { label: '政策咨询', value: '1' },
11
  { label: '服务诉求', value: '2' },
12
  { label: '意见建议', value: '4' },
13
  { label: '问题投诉', value: '5' },
14
]);
15

16
const supportImageList = ['jpg', 'jpeg', 'png', 'gif', 'webp'];
17

18
interface MessageBoardFile {
19
  url: string;
20
  fileSuffix: string;
21
  originalName: string;
22
  ossId: string;
23
}
24

25
const messageBoardFiles = ref<MessageBoardFile[]>([]);
26
const messageBoardImgs = ref<MessageBoardFile[]>([]);
27
const currentMessageBoard = ref();
28
const currentEditType = ref('');
29
const operType = ref('');

展开收起

变量名	类型	作用
`formData`	reactive	表单数据，包含答复内容
`typeOptions`	ref	留言类型选项（政策咨询、服务诉求等）
`supportImageList`	array	支持预览的图片扩展名列表
`MessageBoardFile`	interface	附件文件类型定义
`messageBoardFiles`	ref	非图片附件列表
`messageBoardImgs`	ref	图片附件列表
`currentMessageBoard`	ref	当前留言详情数据
`currentEditType`	ref	当前编辑类型（‘1’ 首次答复，‘2’ 二次答复）
`operType`	ref	操作类型（‘view’ 查看，‘reply’ 答复）

文件类型判断函数

1
function isImageFile(ext: string) {
2
  return supportImageList.some((item) =>
3
    ext.toLocaleLowerCase().includes(item),
4
  );
5
}
6

7
function isPdfFile(ext: string) {
8
  return ext.toLocaleLowerCase().includes('pdf');
9
}

isImageFile：判断文件是否为图片类型，用于区分图片预览和文件下载
isPdfFile：判断文件是否为 PDF 类型，用于特殊处理 PDF 文件

留言类型标签转换

1
function getTypeLabel(id: string) {
2
  let label = '';
3
  const item = typeOptions.value.filter((item) => {
4
    return item.value == id;
5
  })[0];
6
  label = item?.label as '';
7
  return label;
8
}

根据留言类型 ID 获取对应的中文标签。

初始化表单数据

1
async function initFormData(id: any) {
2
  const res = await queryByMessageBoardById(id);
3
  currentMessageBoard.value = res;
4

5
  if (operType.value == 'reply') {
6
    if (!currentMessageBoard.value.secondReplyContent) {
7
      currentEditType.value = '2';
8
    }
9
    if (!currentMessageBoard.value.replyContent) {
10
      currentEditType.value = '1';
11
    }
12
  }
13

14
  if (currentMessageBoard.value.noticeFileId) {
15
    const ossFileList = await fileData(currentMessageBoard.value.noticeFileId);
16
    let files = ossFileList.rows;
17
    messageBoardFiles.value = [];
18
    messageBoardImgs.value = [];
19

20
    if (files.length) {
21
      messageBoardImgs.value = files.filter((item: MessageBoardFile) => {
22
        return isImageFile(item?.fileSuffix);
23
      });
24
      messageBoardFiles.value = files.filter((item: MessageBoardFile) => {
25
        return !isImageFile(item?.fileSuffix);
26
      });
27
    }
28
  }
29
}

展开收起

方法详解：

查询留言详情：调用 queryByMessageBoardById 获取留言数据
判断答复类型（答复模式下）：
- 如果没有首次答复内容（!replyContent），设置 currentEditType = '1'（首次答复）
- 如果已有首次答复但没有二次答复（!secondReplyContent），设置 currentEditType = '2'（二次答复）
处理附件：
- 如果留言包含附件（noticeFileId 存在），调用 fileData 获取附件列表
- 根据文件扩展名过滤图片和非图片文件
- 图片存入 messageBoardImgs，非图片文件存入 messageBoardFiles

表单提交方法

1
function handleSubmit() {
2
  const param = JSON.parse(JSON.stringify(currentMessageBoard.value));
3

4
  if (currentEditType.value == '1') {
5
    param.replyContent = formData.replyContent;
6
    reply(param);
7
  } else {
8
    param.secondReplyContent = formData.replyContent;
9
    replySecond(param);
10
  }
11

12
  handleBack();
13
}

方法详解：

深拷贝数据：使用 JSON.parse(JSON.stringify()) 深拷贝当前留言数据，避免直接修改原数据
判断答复类型：
- currentEditType == '1'：首次答复，将表单内容赋值给 replyContent，调用 reply API
- currentEditType == '2'：二次答复，将表单内容赋值给 secondReplyContent，调用 replySecond API
返回列表：提交完成后调用 handleBack() 返回列表页

撤销答复方法

1
function handleRevoke(type: string) {
2
  if (type == '1') {
3
    revoke(currentMessageBoard.value);
4
  } else {
5
    revokeSecond(currentMessageBoard.value);
6
  }
7

8
  currentEditType.value = '';
9

10
  setTimeout(() => {
11
    initFormData(currentMessageBoard.value.id);
12
  }, 300);
13
}

方法详解：

判断撤销类型：
- type == '1'：撤销首次答复，调用 revoke API
- type == '2'：撤销二次答复，调用 revokeSecond API
重置编辑状态：清空 currentEditType，隐藏编辑区域
刷新数据：延迟 300ms 后重新初始化表单数据，确保后端数据已更新

修改答复方法

1
function handleEdit(type: string) {
2
  currentEditType.value = type;
3

4
  if (type == '1') {
5
    formData.replyContent = currentMessageBoard.value.replyContent;
6
  } else {
7
    formData.replyContent = currentMessageBoard.value.secondReplyContent;
8
  }
9
}

方法详解：

设置编辑类型：将 currentEditType 设置为对应的答复类型
填充表单数据：
- type == '1'：将首次答复内容填充到表单
- type == '2'：将二次答复内容填充到表单

文件下载方法

1
const { apiURL, clientId } = useAppConfig(import.meta.env, import.meta.env.PROD);
2
const accessStore = useAccessStore();
3

4
async function handleDownload(row: any) {
5
  await checkLoginBeforeDownload();
6

7
  const params = {
8
    clientid: clientId,
9
    Authorization: `Bearer ${accessStore.accessToken}`,
10
  };
11

12
  const downloadLink = `${apiURL}/resource/oss/download/${row.ossId}?${stringify(params)}`;
13

14
  downloadByUrl({ fileName: row.fileName, url: downloadLink });
15
}

展开收起

方法详解：

登录检查：调用 checkLoginBeforeDownload 确保用户登录状态有效
构建下载参数：
- clientid：客户端 ID，用于身份验证
- Authorization：Bearer Token，用于身份验证
构建下载链接：
- 基础 URL：${apiURL}/resource/oss/download/
- 文件 ID：${row.ossId}
- 查询参数：使用 stringify 序列化参数
执行下载：调用 downloadByUrl 工具函数触发文件下载

返回列表方法

1
function handleBack() {
2
  currentEditType.value = '';
3
  formData.replyContent = '';
4
  router.back();
5
  closeCurrentTab();
6
}

重置编辑状态和表单内容
调用 router.back() 返回上一页
调用 closeCurrentTab() 关闭当前标签页

组件挂载

1
onMounted(() => {
2
  const type = route.query.type;
3
  operType.value = type as '';
4
  setTabTitle(type == 'view' ? '留言查看' : '留言回复');
5

6
  const id = route.query.id;
7
  initFormData(id);
8
});

获取操作类型（查看或答复）
设置标签页标题
根据留言 ID 初始化表单数据

4.3 模板结构#

留言信息卡片

1
<a-card title="留言信息">
2
  <div class="info-row">
3
    <span class="label"> 留言时间 </span>
4
    <p class="value">{{ currentMessageBoard && currentMessageBoard.noticeTime }}</p>
5
  </div>
6
  <div class="info-row">
7
    <span class="label"> 留言类型 </span>
8
    <p class="value">
9
      {{ currentMessageBoard && currentMessageBoard.noticeType && getTypeLabel(currentMessageBoard.noticeType) }}
10
    </p>
11
  </div>
12
  <!-- ...其他字段 -->
13
</a-card>

字段	说明
留言时间	`noticeTime`
留言类型	`noticeType`，通过 `getTypeLabel` 转换为中文
答复单位	`replyDeptName`
姓名	`userName`
联系方式	`phonenumber`
电子邮箱	`email`
留言标题	`noticeTitle`
留言内容	`noticeContent`

附件展示

1
<div class="info-row file-ul" v-if="messageBoardFiles.length || messageBoardImgs.length">
2
  <div class="img-box">
3
    <a-image
4
      v-for="item in messageBoardImgs"
5
      :width="120"
6
      :height="115"
7
      :src="`${apiURL}/resource/oss/preview/${item.ossId}`"
8
      fallback="..."
9
    />
10
  </div>
11
  <div v-for="item in messageBoardFiles">
12
    <p v-if="isPdfFile(item?.fileSuffix)">
13
      <a href="javascript:;" @click.stop="pdfPreview(item?.url)">
14
        {{ item?.originalName }}
15
      </a>
16
    </p>
17
    <p v-else>
18
      <a href="javascript:;" @click.stop="handleDownload(item)">
19
        {{ item?.originalName }}
20
      </a>
21
    </p>
22
  </div>
23
</div>

展开收起

附件处理逻辑：

图片预览：使用 a-image 组件展示图片，通过 apiURL 构建预览地址
PDF 文件：点击后调用 pdfPreview 方法（内部调用下载）
其他文件：点击后调用 handleDownload 方法下载

首次答复展示

1
<template v-if="currentMessageBoard && currentMessageBoard.replyContent">
2
  <div class="info-row">
3
    <p class="bolder">
4
      <span>答复单位：{{ (currentMessageBoard && currentMessageBoard.replyDeptName) || '/' }}</span>
5
      <span>办理人：{{ (currentMessageBoard && currentMessageBoard.handleUserName) || '/' }}</span>
6
      <span>办理时间：{{ (currentMessageBoard && currentMessageBoard.handleTime) || '/' }}</span>
7
    </p>
8
  </div>
9
  <div class="info-row reply-row" v-if="currentMessageBoard && currentMessageBoard.replyContent">
10
    <p class="reply-info">
11
      {{ (currentMessageBoard && currentMessageBoard.replyContent) || '/' }}
12
    </p>
13
    <div v-if="currentMessageBoard.replyContent && !currentMessageBoard.handleGrade">
14
      <span @click="handleRevoke('1')">撤销</span>
15
      <span @click="handleEdit('1')">修改</span>
16
    </div>
17
  </div>
18
</template>

展开收起

二次反馈展示

1
<a-card title="二次反馈" v-if="currentMessageBoard && currentMessageBoard.secondContent">
2
  <div class="info-row">
3
    <span class="label"> 留言时间 </span>
4
    <p class="value">{{ currentMessageBoard && currentMessageBoard.rateTime }}</p>
5
  </div>
6
  <div class="info-row">
7
    <span class="label"> 反馈内容 </span>
8
    <p class="value">{{ currentMessageBoard && currentMessageBoard.secondContent }}</p>
9
  </div>
10
  <div class="info-row reply-row" v-if="currentMessageBoard && currentMessageBoard.secondReplyContent">
11
    <p class="reply-info">
12
      {{ (currentMessageBoard && currentMessageBoard.secondReplyContent) || '/' }}
13
    </p>
14
    <div v-if="currentMessageBoard.secondReplyContent">
15
      <span @click="handleRevoke('2')">撤销</span>
16
      <span @click="handleEdit('2')">修改</span>
17
    </div>
18
  </div>
19
</a-card>

展开收起

答复表单

1
<a-card title="答复内容" v-else>
2
  <a-form
3
    ref="formRef"
4
    :style="{ width: '80%' }"
5
    :model="formData"
6
    :wrapper-col="{ span: 24 }"
7
    autocomplete="off"
8
  >
9
    <a-form-item label="">
10
      <a-textarea
11
        v-model:value="formData.replyContent"
12
        :rows="4"
13
        placeholder="请输入内容，最多支持输入500字"
14
        :maxlength="500"
15
      ></a-textarea>
16
    </a-form-item>
17
  </a-form>
18
  <div class="info-row btn-row">
19
    <a-button @click="handleBack" class="default-btn"> 返回 </a-button>
20
    <a-button type="primary" @click="handleSubmit"> 提交 </a-button>
21
  </div>
22
</a-card>

展开收起

4.4 样式设计#

1
:deep(.ant-card) {
2
  margin-bottom: 16px;
3
}
4

5
.info-row {
6
  display: flex;
7
  width: 100%;
8
  margin-bottom: 8px;
9
  justify-content: flex-start;
10
  align-items: flex-start;
11

12
  .label {
13
    width: 80px;
14
    min-width: 80px;
15
  }
16

17
  .bolder {
18
    font-weight: bold;
19
    font-size: 14px;
20
    line-height: 48px;
21

22
    span {
23
      margin-right: 18px;
24
    }
25
  }
26
}
27

28
.reply-row {
29
  display: flex;
30
  justify-content: space-between;
31

32
  .reply-info {
33
    text-indent: 2em;
34
    background-color: rgb(247, 248, 250);
35
    padding: 16px;
36
    flex: 1;
37
    box-sizing: border-box;
38
  }
39

40
  div {
41
    margin-left: 10px;
42
  }
43

44
  div > span {
45
    margin-right: 6px;
46
    cursor: pointer;
47
    color: #1476ff;
48
  }
49
}
50

51
.btn-row {
52
  justify-content: center;
53
  align-items: center;
54

55
  .default-btn {
56
    margin-right: 40px;
57
  }
58
}
59

60
.file-ul {
61
  display: flex;
62
  flex-direction: column;
63
  padding-left: 30px;
64

65
  .img-box {
66
    display: flex;
67
    flex-direction: row;
68

69
    :deep(.ant-image) {
70
      margin-right: 16px !important;
71
    }
72
  }
73

74
  div {
75
    margin-bottom: 4px;
76
  }
77
}

展开收起

样式类	说明
`.info-row`	信息行布局，使用 flex 排列标签和值
`.label`	标签固定宽度 80px
`.bolder`	答复信息加粗显示
`.reply-row`	答复内容行，包含答复文本和操作按钮
`.reply-info`	答复内容区域，灰色背景，首行缩进
`.btn-row`	按钮行，居中排列
`.file-ul`	附件列表区域
`.img-box`	图片预览区域，横向排列

5. API 接口详解#

5.1 接口定义#

1
enum Api {
2
  root = '/manager/noticeBoard',
3
  noticeBoardList = '/manager/noticeBoard/list',
4
  deptTree = '/system/user/deptTree',
5
  fileData = '/manager/fileData/list',
6
}

API 常量	路径	说明
`root`	`/manager/noticeBoard`	基础路径
`noticeBoardList`	`/manager/noticeBoard/list`	留言列表
`deptTree`	`/system/user/deptTree`	部门树
`fileData`	`/manager/fileData/list`	附件列表

5.2 接口函数#

函数	方法	路径	说明
`fileData`	GET	`/manager/fileData/list`	获取附件列表
`noticeBoardList`	GET	`/manager/noticeBoard/list`	获取留言列表
`queryByMessageBoardById`	GET	`/manager/noticeBoard/{id}`	根据 ID 查询留言详情
`reply`	POST	`/manager/noticeBoard/reply`	首次答复
`replySecond`	POST	`/manager/noticeBoard/replySecond`	二次答复
`download`	POST	`/manager/noticeBoard/export`	导出留言列表
`queryDeptTree`	GET	`/system/user/deptTree`	获取部门树
`revoke`	POST	`/manager/noticeBoard/revoke`	撤销首次答复
`revokeSecond`	POST	`/manager/noticeBoard/revokeSecond`	撤销二次答复
`updatePublic`	POST	`/manager/noticeBoard/updatePublic`	更新公开状态

5.3 接口实现详解#

获取留言列表

1
export function noticeBoardList(params?: PageQuery) {
2
  return requestClient.get<any[]>(Api.noticeBoardList, { params });
3
}

使用 GET 方法
参数通过 query string 传递
返回列表数据

查询留言详情

1
export function queryByMessageBoardById(id: string) {
2
  return requestClient.get<any>(`${Api.root}/${id}`);
3
}

使用 GET 方法
通过路径参数传递留言 ID
返回留言详情对象

首次答复

1
export function reply(data: any) {
2
  return requestClient.postWithMsg<any>(`${Api.root}/reply`, data);
3
}

使用 POST 方法
使用 postWithMsg 封装，自动处理成功/失败消息提示
传入完整的留言对象，包含答复内容

二次答复

1
export function replySecond(data: any) {
2
  return requestClient.postWithMsg<any>(`${Api.root}/replySecond`, data);
3
}

与首次答复类似，但路径不同

撤销答复

1
export function revoke(data: any) {
2
  return requestClient.postWithMsg<any>(`${Api.root}/revoke`, data);
3
}
4

5
export function revokeSecond(data: any) {
6
  return requestClient.postWithMsg<any>(`${Api.root}/revokeSecond`, data);
7
}

撤销首次答复和二次答复
使用 postWithMsg 封装

更新公开状态

1
export function updatePublic(data: any) {
2
  return requestClient.postWithMsg<any>(`${Api.root}/updatePublic`, data);
3
}

更新留言的公开状态
参数包含 id 和 isPublic

6. 数据模型#

6.1 留言数据结构#

1
interface MessageBoard {
2
  id: string;                    // 留言 ID
3
  noticeTitle: string;           // 留言标题
4
  noticeContent: string;         // 留言内容
5
  noticeType: string;            // 留言类型（1-政策咨询，2-服务诉求，4-意见建议，5-问题投诉）
6
  noticeTime: string;            // 留言时间
7
  userName: string;              // 用户姓名
8
  phonenumber: string;           // 联系方式
9
  email: string;                 // 电子邮箱
10
  isPublic: string;              // 是否公开（0-不公开，1-公开）
11
  handleStatus: string;          // 办理状态（0-待答复，1-已答复）
12
  replyDeptName: string;         // 答复单位名称
13
  handleUserName: string;        // 办理人姓名
14
  handleTime: string;            // 办理时间
15
  replyContent: string;          // 首次答复内容
16
  secondContent: string;         // 二次反馈内容
17
  secondReplyContent: string;    // 二次答复内容
18
  noticeFileId: string;          // 附件关联 ID
19
}

展开收起

6.2 附件数据结构#

1
interface MessageBoardFile {
2
  url: string;           // 文件 URL
3
  fileSuffix: string;    // 文件扩展名
4
  originalName: string;  // 原始文件名
5
  ossId: string;         // OSS 文件 ID
6
}

文件下载前进行登录检查：

调用 checkLoginBeforeDownload 确保登录状态有效
在下载链接中携带 Authorization Token
使用 clientid 进行身份验证

开发体会#

实习带教教了一下SVN的使用
SVN

SVN

需求文档上的操作人员加上了我的名字,突然有了一点参与感了·≥﹏≤·

后端开发日记⑦：飞行任务与大疆开放平台适配

Thu, 16 Jul 2026 00:00:00 GMT

飞行模块同时面对两套数据：项目数据库中的配送任务，以及大疆运载云端互联平台中的设备、航线和任务。两者不能完全混为一体，否则第三方接口一旦变化，订单详情也会跟着失效。

1. 本地任务保存业务关系#

HyFlightTask 负责连接订单和外部飞行数据，保存当前任务 ID、大疆任务 ID、航线标识、任务状态等信息。订单通过 currentTaskId 指向当前飞行任务，过程日志也可以记录同一个任务 ID。

本地表回答“这次配送使用哪个飞行任务”，大疆平台回答“设备、航线和实时任务现在怎样”。职责分开后，即使外部平台暂时不可用，订单关系仍然存在。

2. 通用客户端统一鉴权#

DjiApiClient 封装 GET、POST、PUT、DELETE 和表单请求。每次调用都会生成：

1
X-DJI-Access-Key
2
X-DJI-Timestamp
3
X-DJI-Nonce
4
X-DJI-Signature

签名使用请求方法、时间戳和随机数等信息计算，AccessKey 与 SecretKey 只从服务端配置读取。前端永远不接触密钥，也不负责生成签名。

客户端还统一处理连接超时、请求超时、JSON 序列化、非 2xx 响应和空响应。业务 Service 不需要在每个 API 方法里重复这些代码。

3. OpenAPI Service 只表达业务动作#

通用客户端之上再建立 DjiOpenApiServiceImpl，提供设备、拓扑、直播、航线、地图元素、指令和任务等方法：

1
listDevices(params)
2
getWayline(waylineId, params)
3
createTask(body)
4
startTask(taskId, params)
5
getTaskTrack(taskId, params)

Service 负责拼接带 groupId 的路径并编码路径参数，Controller 只转发经过权限校验的请求。这样第三方 URL 变化时，修改集中在适配层。

4. 订单轨迹如何拿到航线#

用户查看订单轨迹时，后端先查本地飞行任务，再尝试找到大疆原始航线 ID，随后请求航线详情。第三方返回的点字段可能使用 longitude/lng/lon 与 latitude/lat 等不同命名，因此要先归一化：

1
Double lng = numberValue(pickFirst(point,
2
        "longitude", "lng", "lon"));
3
Double lat = numberValue(pickFirst(point,
4
        "latitude", "lat"));

无效坐标和零坐标会被过滤，高度与速度存在时再附加到结果中。成功获取的航线标记为 WGS84，让前端知道后续需要做什么坐标处理。

5. 第三方失败不能拖垮订单详情#

航线是详情的增强信息，不是读取订单的必要条件。大疆接口异常时，后端不会让整个订单详情失败，而是回退到接驳点与船舶坐标组成的基础路线，并标记为 GCJ02。

1
大疆航线成功 -> 返回完整航点
2
大疆航线失败 -> 返回起点和终点
3
基础坐标也不足 -> 只返回订单与任务信息

这种降级要根据业务重要性决定。创建或启动飞行任务失败不能被忽略，但展示辅助航线失败可以回退。

6. 配置对象如何承接 YAML#

大疆连接参数使用 @ConfigurationProperties 绑定：

1
@ConfigurationProperties(prefix = "dji.api")
2
public class DjiApiProperties {
3
    private String baseUrl;
4
    private String accessKey;
5
    private String secretKey;
6
    private String groupId;
7
    private Duration connectTimeout;
8
    private Duration requestTimeout;
9
}

YAML 中的 connect-timeout: 5s 会直接转换为 Duration，比读取字符串后手动解析更安全。配置对象集中描述第三方平台需要的所有参数，客户端构造时只依赖这一个对象。

真实密钥不应直接写在仓库配置中，可以改为：

1
dji:
2
  api:
3
    base-url: ${DJI_API_BASE_URL:https://ta-api-cn.dji.com}
4
    access-key: ${DJI_ACCESS_KEY:}
5
    secret-key: ${DJI_SECRET_KEY:}
6
    group-id: ${DJI_GROUP_ID:}

冒号后面是缺省值；密钥缺省为空，客户端会在发送请求前明确提示“AK/SK 未配置”，而不是带着空请求头访问第三方。

7. 通用请求方法逐段理解#

1
public Object request(
2
        String method,
3
        String path,
4
        Object body,
5
        String contentType) {
6
    try {
7
        String normalizedMethod =
8
                method.toUpperCase(Locale.ROOT);
9
        HttpRequest request = buildRequest(
10
                normalizedMethod, path, body, contentType);
11
        HttpResponse<String> response = httpClient.send(
12
                request,
13
                HttpResponse.BodyHandlers.ofString(
14
                        StandardCharsets.UTF_8));
15

16
        if (response.statusCode() < 200
17
                || response.statusCode() >= 300) {
18
            throw new ServiceException(
19
                    "大疆 API 服务响应异常");
20
        }
21
        if (StringUtils.isEmpty(response.body())) {
22
            return Collections.emptyMap();
23
        }
24
        return objectMapper.readValue(
25
                response.body(), Object.class);
26
    } catch (ServiceException e) {
27
        throw e;
28
    } catch (Exception e) {
29
        throw new ServiceException("调用大疆 API 服务失败");
30
    }
31
}

展开收起

方法先统一 HTTP 动词大小写，再构造请求。响应判断使用完整 2xx 范围，而不是只接受 200，因为创建或无内容响应可能使用其他成功状态码。

空响应统一返回空 Map，调用方就不必反复处理空字符串。已经属于业务提示的 ServiceException 原样抛出，网络、编码和 JSON 解析等底层异常则被转换成不暴露密钥与内部堆栈的统一信息。

日志可以记录方法、路径、状态码和第三方请求 ID，但要避免输出签名、SecretKey 或包含个人数据的完整请求体。

8. 请求签名代码逐行说明#

1
private String sign(
2
        String method,
3
        String timestamp,
4
        String nonce) throws Exception {
5
    String signText = properties.getAccessKey()
6
            + method + timestamp + nonce;
7
    Mac mac = Mac.getInstance("HmacSHA256");
8
    mac.init(new SecretKeySpec(
9
            properties.getSecretKey().getBytes(
10
                    StandardCharsets.UTF_8),
11
            "HmacSHA256"));
12
    byte[] digest = mac.doFinal(
13
            signText.getBytes(StandardCharsets.UTF_8));
14
    return toHex(digest);
15
}

展开收起

签名原文的拼接顺序必须与平台协议完全一致。Locale.ROOT 统一 HTTP 动词大小写，UTF-8 统一字符串到字节的编码，否则同一文本在不同环境可能算出不同结果。

HMAC 与普通哈希的区别是它使用 SecretKey。服务端和大疆平台持有相同密钥，平台用相同原文重新计算，结果一致才接受请求。SecretKey 本身不会通过网络发送。

摘要字节最后转换成小写十六进制字符串。若平台要求 Base64 或大写十六进制，转换方式也必须严格匹配，不能只确认算法名相同。

9. buildRequest 怎样区分请求体#

1
if ("GET".equals(method) || "DELETE".equals(method)) {
2
    return builder.method(
3
            method, HttpRequest.BodyPublishers.noBody())
4
            .build();
5
}
6

7
if (StringUtils.isEmpty(contentType)) {
8
    return builder.method(
9
            method, HttpRequest.BodyPublishers.noBody())
10
            .build();
11
}
12

13
builder.header("Content-Type", contentType);
14
String requestBody =
15
        "application/x-www-form-urlencoded".equals(contentType)
16
                ? String.valueOf(body)
17
                : toJson(body);
18
return builder.method(
19
        method,
20
        HttpRequest.BodyPublishers.ofString(
21
                requestBody, StandardCharsets.UTF_8))
22
        .build();

展开收起

GET 和 DELETE 的参数通过查询字符串传递；POST 可以选择 JSON、表单或无请求体。postWithQuery 就使用无 Content-Type 的 POST，用于平台要求“参数在 URL、请求体为空”的特殊接口。

表单编码不能简单使用 Map.toString()，所以公共客户端先通过 buildFormBody 对键和值分别 URL 编码，再交给这里发送。

10. 路径和查询参数如何编码#

1
private String groupPath(String template, String... variables) {
2
    String groupId = properties.getGroupId();
3
    if (StringUtils.isEmpty(groupId)) {
4
        throw new ServiceException("大疆运载 group_id 未配置");
5
    }
6
    Object[] args = new Object[variables.length + 1];
7
    args[0] = encodePathSegment(groupId);
8
    for (int i = 0; i < variables.length; i++) {
9
        args[i + 1] = encodePathSegment(variables[i]);
10
    }
11
    return String.format(template, args);
12
}

路径段和查询参数都需要编码，但规则并不完全相同。路径中的空格应编码为 %20，而标准表单编码可能产生 +，因此 encodePathSegment 会把 + 再替换成 %20。

外部 ID 不能不经处理直接插入路径，否则斜杠、问号等字符可能改变 URL 结构。

11. 航线响应归一化的代码#

1
for (Map<String, Object> item : getObjectList(source)) {
2
    Double longitude = numberValue(pickFirst(
3
            item, "longitude", "lng", "lon"));
4
    Double latitude = numberValue(pickFirst(
5
            item, "latitude", "lat"));
6
    if (longitude == null || latitude == null
7
            || longitude == 0D || latitude == 0D) {
8
        continue;
9
    }
10
    Map<String, Object> point = new LinkedHashMap<>();
11
    point.put("longitude", longitude);
12
    point.put("latitude", latitude);
13
    Object height = pickFirst(
14
            item, "height", "altitude", "ellipsoid_height");
15
    if (height != null) {
16
        point.put("height", height);
17
    }
18
    result.add(point);
19
}

展开收起

pickFirst 让适配层兼容第三方不同版本的字段命名，numberValue 同时接受 JSON 数字和数字字符串。使用 LinkedHashMap 保持字段输出顺序稳定，便于日志和接口调试。

归一化后的对象只保留业务真正需要的经纬度、高度和速度。第三方响应中其他字段不会直接扩散到前端契约。

12. 降级代码应该捕获到哪里#

订单详情只把第三方航线当作增强信息，因此调用处捕获异常：

1
try {
2
    Object response = djiOpenApiService
3
            .getWayline(waylineId, Collections.emptyMap());
4
    List<Map<String, Object>> points =
5
            normalizeDjiWaylinePoints(extractPoints(response));
6
    order.setWaylinePoints(points);
7
    order.setRouteCoordinateSystem("WGS84");
8
} catch (Exception ignored) {
9
    // 继续构造基础路线
10
}

实际项目中不建议完全忽略日志，可以用 debug 或带频率限制的 warn 记录订单 ID 和第三方请求 ID。这样用户不受影响，运维仍能发现航线服务长期异常。

降级只包住获取增强数据的最小范围，不能把整个订单查询都包在空 catch 中，否则数据库错误也会被误认为“没有航线”。

13. 本篇小结#

第三方平台接入最好分成“通用 HTTP 客户端、平台能力适配、本地业务编排”三层。密钥和签名停留在服务端，外部字段在边界处归一化，再为非关键展示准备回退数据，业务代码才不会完全受制于外部接口。

后端开发日记⑥：配送凭证与受保护文件流

Mon, 13 Jul 2026 00:00:00 GMT

订单截图、货品图、签收图和异常证据都属于配送凭证。它们不能只保存一个公开 URL，因为图片包含订单信息，访问权限应和订单权限保持一致。本篇记录从上传到预览的完整后端链路。

1. 文件和业务记录分开保存#

上传成功后，文件写入配置的 profile 目录，数据库只记录元数据：

1
orderId          关联订单
2
orderVersion     上传时的订单版本
3
proofType        凭证类型
4
storagePath      服务端存储路径
5
uploaderType     WX_USER / SYS_USER
6
uploaderId       上传人
7
proofStatus      凭证状态

这样可以按订单、版本和类型查询凭证，也可以在不搬动文件的情况下修改业务状态。

2. 上传前先校验订单#

用户端上传必须确认订单属于当前登录用户；管理端上传至少确认订单存在且未删除。权限检查发生在保存文件之前，避免无权请求先占用磁盘空间。

1
checkCurrentUserOrderOwner(orderId);
2
return uploadDeliveryProof(file, orderId, proofType, sortNo,
3
        "WX_USER", SecurityUtils.getUserId());

公共上传方法负责文件非空、订单 ID、凭证类型等通用校验，两端入口只处理各自的身份规则。

3. 凭证绑定订单版本#

订单可能被驳回后修改。新上传的图片如果仍和旧资料混在一起，管理端无法判断它对应哪次提交。

上传时查询该订单已有的最大历史版本，没有历史时视为第一版；有历史时使用下一版本号。凭证因此可以随订单版本一起回溯。

4. 列表不返回真实路径#

返回对象 HyDeliveryProofVo 包含凭证 ID、类型、排序、上传时间和 hasImage，但不返回 storagePath。前端需要图片时，再携带 Token 请求专门的图片接口。

这避免了两个问题：

客户端拿到服务器目录结构；
用户绕过业务接口，拼接静态路径访问其他订单图片。

5. 安全解析本地路径#

图片读取统一经过 ProtectedFileUtils。工具先要求路径使用系统资源前缀，再把相对路径解析到 profile 根目录：

1
Path root = Paths.get(SystemConfig.getProfile())
2
        .toAbsolutePath().normalize();
3
Path target = root.resolve(relativePath).normalize();
4
if (!target.startsWith(root)) {
5
    throw new ServiceException("文件路径非法");
6
}

normalize() 与 startsWith(root) 可以拦截通过 ../ 逃逸到上传目录之外的路径。随后还要确认目标是普通文件，而不是只检查路径存在。

6. 通过鉴权接口输出文件流#

Controller 根据文件类型设置 Content-Type，使用 inline 让浏览器或小程序直接预览，并通过 Files.copy 写入响应流。用户端读取前再次校验订单归属，不能因为知道 proofId 就获得图片。

删除凭证同样执行“查凭证 -> 查订单归属 -> 删除记录”的顺序。文件访问权限必须覆盖查询、读取和删除三个入口，而不是只保护上传。

7. 公共上传方法逐行说明#

用户端与管理端最终都进入同一个上传方法：

1
private HyDeliveryProofVo uploadDeliveryProof(
2
        MultipartFile file,
3
        Long orderId,
4
        String proofType,
5
        Long sortNo,
6
        String uploaderType,
7
        Long uploaderId) throws Exception {
8
    if (file == null || file.isEmpty()) {
9
        throw new ServiceException("上传文件不能为空");
10
    }
11
    if (orderId == null) {
12
        throw new ServiceException("订单ID不能为空");
13
    }
14
    if (isBlank(proofType)) {
15
        throw new ServiceException("凭证类型不能为空");
16
    }
17

18
    String fileName = FileUploadUtils.upload(
19
            SystemConfig.getUploadPath(), file);
20
    HyDeliveryProof proof = new HyDeliveryProof();
21
    proof.setOrderId(orderId);
22
    proof.setOrderVersion(getCurrentOrderVersionNo(orderId));
23
    proof.setProofType(proofType);
24
    proof.setSortNo(sortNo);
25
    proof.setStoragePath(fileName);
26
    proof.setProofStatus("NORMAL");
27
    proof.setUploaderType(uploaderType);
28
    proof.setUploaderId(uploaderId);
29
    proof.setUploadTime(new Date());
30
    mapper.insertHyDeliveryProof(proof);
31
    return toVo(proof);
32
}

展开收起

参数校验发生在磁盘写入之前，避免明显错误请求留下孤立文件。uploaderType 和 uploaderId 由不同入口传入，但前端不能自定义：用户入口固定为 WX_USER，管理端固定为 SYS_USER。

上传成功后立即写数据库。如果数据库插入失败，磁盘文件不会随数据库事务自动删除，这是文件系统和数据库跨资源一致性问题。可以在捕获异常时删除刚上传文件，或者先写临时目录，数据库成功后再转为正式文件。

8. 版本号计算代表哪一版#

1
private Long getCurrentOrderVersionNo(Long orderId) {
2
    Long maxVersionNo = historyMapper
3
            .selectMaxVersionNoByOrderId(orderId);
4
    return maxVersionNo == null ? 1L : maxVersionNo + 1L;
5
}

历史表保存修改前版本，因此没有历史时主订单是第一版；存在第 1 版历史时，当前主订单已经是第二版。凭证上传时使用 max + 1，正好对应当前主订单版本。

理解这个约定很重要。如果历史表改成保存修改后版本，这段算法也必须随之调整，否则图片会错绑版本。

9. VO 转换如何隐藏路径#

1
private HyDeliveryProofVo toVo(HyDeliveryProof proof) {
2
    HyDeliveryProofVo vo = new HyDeliveryProofVo();
3
    vo.setProofId(proof.getProofId());
4
    vo.setOrderId(proof.getOrderId());
5
    vo.setOrderVersion(proof.getOrderVersion());
6
    vo.setProofType(proof.getProofType());
7
    vo.setSortNo(proof.getSortNo());
8
    vo.setUploaderType(proof.getUploaderType());
9
    vo.setUploadTime(proof.getUploadTime());
10
    vo.setHasImage(StringUtils.isNotEmpty(
11
            proof.getStoragePath()));
12
    return vo;
13
}

VO 不设置 storagePath，而是把它折叠成布尔值。页面知道“有图片”，需要显示时使用 proofId 请求鉴权接口。

这样即使服务器从本地磁盘迁移到对象存储，前端接口也不需要跟着改变路径格式。VO 同时承担了安全隔离和存储实现解耦。

10. 受保护路径如何拦截目录穿越#

1
String relativePath = resourcePath.substring(
2
        Constants.RESOURCE_PREFIX.length() + 1);
3
Path root = Paths.get(SystemConfig.getProfile())
4
        .toAbsolutePath().normalize();
5
Path target = root.resolve(relativePath).normalize();
6

7
if (!target.startsWith(root)) {
8
    throw new ServiceException("文件路径非法");
9
}
10
if (!Files.isRegularFile(target)) {
11
    throw new ServiceException("文件不存在");
12
}

假设根目录是 D:/upload，恶意路径包含 ../config.yml。resolve 后可能暂时得到 D:/upload/../config.yml，normalize 会把它化简为 D:/config.yml，随后 startsWith(root) 返回 false。

只做字符串包含判断并不安全，例如 D:/upload-backup 也包含 D:/upload。使用规范化后的 Path 关系更可靠。

11. Controller 怎样输出图片#

1
private void writeFile(
2
        HttpServletResponse response,
3
        FileStreamVo file) throws IOException {
4
    response.setContentType(file.getContentType());
5
    response.setHeader(
6
            "Cache-Control", "private, max-age=300");
7
    response.setHeader(
8
            "Content-Disposition",
9
            "inline; filename=\"" + encode(file.getFileName()) + "\"");
10
    Files.copy(file.getPath(), response.getOutputStream());
11
}

inline 表示浏览器可以直接预览，private 表示共享缓存不应该保存这份鉴权资源，max-age=300 允许用户自己的浏览器短时间缓存。

文件名进入响应头前必须编码，内容类型优先通过系统探测，无法识别时回退到 application/octet-stream。对于大文件还可以增加分段读取、响应长度与限速，避免一次把整个文件加载进内存。

12. 删除凭证还缺少哪一步#

当前删除方法校验凭证存在和订单归属后删除数据库记录：

1
HyDeliveryProof proof = getExistingProof(proofId);
2
checkCurrentUserOrderOwner(proof.getOrderId());
3
return mapper.deleteHyDeliveryProofByProofId(proofId);

如果业务要求物理删除文件，还需要处理数据库与磁盘的一致性；如果为了审计保留文件，则可以采用逻辑删除并设置保留期限。无论选择哪种，都不应在没有明确策略时让数据库记录和磁盘文件无限增长。

13. 本篇小结#

受保护图片的关键不是换一个上传组件，而是把业务权限放到文件之前。数据库保存可查询的元数据，VO 隐藏存储路径，读取时验证资源归属并限制路径落在指定根目录，才能形成闭合的文件安全链路。

实习笔记②

Sun, 12 Jul 2026 00:00:00 GMT

修复科普资源上传模块中的两个问题：

getAllDept 函数在 system.ts 中读取 split 时出现 TypeError（undefined 值）
新增/编辑资源后列表没有刷新

1. 模块概述#

科普资源上传模块位于 src/views/popularization/resources/resources-upload 目录下，包含三个文件：

文件	功能
`index.vue`	资源列表页，展示已上传的资源列表，支持查看、编辑、删除操作
`form.vue`	资源上传/编辑表单页，包含资源名称、分类、标签、类型、封面、内容等字段
`data.ts`	表格列配置和查询表单配置

页面流程#

1
index.vue（资源列表）
2
    ↓ 点击"新增"按钮
3
form.vue（上传表单）
4
    ↓ 提交表单后返回
5
index.vue（资源列表刷新）

2. index.vue（资源列表页）#

2.1 页面功能#

展示科普资源列表，支持：

按资源名称、上传时间、审核状态筛选
分页展示
查看、编辑、批量删除操作

2.2 代码实现#

导入模块

1
import type { VbenFormProps } from '@vben/common-ui';
2
import type { VxeGridProps } from '#/adapter/vxe-table';
3
import { getAllDeptId } from '#/utils/system';
4
import { Page } from '@vben/common-ui';
5
import { onActivated, onMounted } from 'vue';
6
import { Modal, Space } from 'ant-design-vue';
7
import { useVbenVxeGrid, vxeCheckboxChecked } from '#/adapter/vxe-table';
8
import { columns, querySchema } from './data';
9
import { useRouter } from 'vue-router';
10
import {
11
  popularizationResourceList,
12
  popularizationResourceDelete,
13
} from '#/api/business/science-popularization-resources/resources-upload/index';

导入项	说明
`VbenFormProps`	Vben 表单组件属性类型定义
`VxeGridProps`	Vxe 表格组件属性类型定义
`getAllDeptId`	获取当前用户所属独立法人单位 ID
`Page`	Vben 页面布局组件
`useVbenVxeGrid`	封装 Vxe 表格和查询表单的组合式函数
`columns`	表格列配置（来自 data.ts）
`querySchema`	查询表单配置（来自 data.ts）
`popularizationResourceList`	获取资源列表 API
`popularizationResourceDelete`	删除资源 API

表单配置

1
const formOptions: VbenFormProps = {
2
  commonConfig: {
3
    labelWidth: 80,
4
    componentProps: {
5
      allowClear: true,
6
    },
7
  },
8
  schema: querySchema(),
9
  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4',
10
  fieldMappingTime: [
11
    [
12
      'uploadTime',
13
      ['params[beginTime]', 'params[endTime]'],
14
      ['YYYY-MM-DD 00:00:00', 'YYYY-MM-DD 23:59:59'],
15
    ],
16
  ],
17
};

展开收起

配置项	作用
`labelWidth`	表单标签宽度
`allowClear`	表单组件支持清空
`schema`	查询表单字段定义
`wrapperClass`	表单网格布局样式类
`fieldMappingTime`	日期范围选择器字段映射，将 `uploadTime` 转换为 `beginTime` 和 `endTime`

表格配置

1
const gridOptions: VxeGridProps = {
2
  checkboxConfig: {
3
    highlight: true,
4
    reserve: true,
5
  },
6
  columns,
7
  height: 'auto',
8
  border: true,
9
  keepSource: true,
10
  pagerConfig: {},
11
  proxyConfig: {
12
    ajax: {
13
      query: async ({ page }, formValues = {}) => {
14
        return await popularizationResourceList({
15
          pageNum: page.currentPage,
16
          pageSize: page.pageSize,
17
          ...formValues,
18
          sourceDeptId: getAllDeptId() ?? ''
19
        });
20
      },
21
    },
22
  },
23
  rowConfig: {
24
    keyField: 'id',
25
  },
26
  id: 'resources-upload-index',
27
};

展开收起

配置项	作用
`checkboxConfig.highlight`	选中行高亮显示
`checkboxConfig.reserve`	翻页时保留选中状态
`proxyConfig.ajax.query`	数据代理查询函数，自动处理分页参数
`sourceDeptId`	传递当前部门 ID 进行数据过滤
`rowConfig.keyField`	行唯一标识字段

创建表格实例

1
const [BasicTable, tableApi] = useVbenVxeGrid({
2
  formOptions,
3
  gridOptions,
4
} as any);

useVbenVxeGrid 返回两个值：

BasicTable：表格组件，用于模板渲染
tableApi：表格 API，用于操作表格（如刷新、获取选中行等）

查看操作

1
function handleView(row: any) {
2
  router.push({
3
    path: '../resourcesExamine/form',
4
    query: {
5
      id: row.id,
6
      type: 'view',
7
    },
8
  });
9
}

跳转到资源审核详情页，通过 query 参数传递资源 ID 和操作类型。

新增操作

1
function handleAdd(row: any) {
2
  router.push({
3
    path: './form',
4
    query: {
5
      type: 'add',
6
    },
7
  });
8
}

跳转到表单页，标记为新增模式。

编辑操作

1
function handleEdit(row: any) {
2
  router.push({
3
    path: './form',
4
    query: {
5
      id: row.id,
6
      type: 'edit',
7
    },
8
  });
9
}

跳转到表单页，传递资源 ID 和编辑类型。

批量删除操作

1
function handleMultiDelete() {
2
  const rows = tableApi.grid.getCheckboxRecords();
3
  const ids = rows.map((row: any) => row.id);
4
  Modal.confirm({
5
    title: '提示',
6
    okType: 'danger',
7
    content: `确认删除选中的${ids.length}条记录吗？`,
8
    onOk: async () => {
9
      await popularizationResourceDelete(ids);
10
      await tableApi.query();
11
    },
12
  });
13
}

获取选中行数据
提取 ID 数组
弹出确认框
调用删除 API
刷新表格数据

列表刷新机制

1
onActivated(() => {
2
  tableApi.query();
3
});
4
onMounted(() => {
5
  tableApi.query();
6
});

生命周期钩子	作用
`onMounted`	组件首次挂载时执行查询
`onActivated`	组件从缓存中激活时执行查询（关键：解决列表不刷新问题）

2.3 模板结构#

1
<template>
2
  <Page :auto-content-height="true">
3
    <BasicTable table-title="资源列表">
4
      <template #toolbar-tools>
5
        <Space>
6
          <a-button type="primary" @click="handleAdd">
7
            {{ $t('pages.common.add') }}
8
          </a-button>
9
          <a-button :disabled="!vxeCheckboxChecked(tableApi)" danger type="primary" @click="handleMultiDelete">
10
            {{ $t('pages.common.delete') }}
11
          </a-button>
12
        </Space>
13
      </template>
14
      <template #action="{ row }">
15
        <Space>
16
          <ghost-button @click.stop="handleView(row)"> 查看 </ghost-button>
17
          <ghost-button @click.stop="handleEdit(row)">
18
            {{ $t('pages.common.edit') }}
19
          </ghost-button>
20
        </Space>
21
      </template>
22
    </BasicTable>
23
  </Page>
24
</template>

展开收起

模板部分	作用
`#toolbar-tools`	工具栏插槽，放置新增和删除按钮
`#action`	操作列插槽，放置查看和编辑按钮
`vxeCheckboxChecked(tableApi)`	判断是否有选中行，控制删除按钮禁用状态

3. form.vue（资源上传表单页）#

3.1 页面功能#

资源上传/编辑表单，支持三种资源类型：

图文：资源名称、分类、标签、封面、富文本正文
音频：资源名称、分类、标签、封面、音频文件
视频：资源名称、分类、标签、封面、视频文件

3.2 代码实现#

导入模块

1
import { Page } from '@vben/common-ui';
2
import { useTabs } from '@vben/hooks';
3
import { getAllDept } from '#/utils/system';
4
import { ref } from 'vue';
5
import { FileUpload, ImageUpload } from '#/components/upload';
6
import { Tinymce } from '#/components/tinymce/index';
7
import { dictDataList } from '#/api/business/science-popularization-resources/category/index';
8
import {
9
  add,
10
  update,
11
  queryPopularizationResourceById,
12
  fileData,
13
} from '#/api/business/science-popularization-resources/resources-upload/index';

导入项	说明
`useTabs`	Vben 标签页管理钩子
`getAllDept`	获取当前用户所属独立法人单位信息
`FileUpload`	文件上传组件
`ImageUpload`	图片上传组件
`Tinymce`	富文本编辑器组件
`dictDataList`	获取字典数据 API
`add/update`	新增/编辑资源 API

资源类型选项

1
const typeOptions = ref([
2
  {
3
    value: '1',
4
    label: '图文',
5
  },
6
  {
7
    value: '2',
8
    label: '音频',
9
  },
10
  {
11
    value: '3',
12
    label: '视频',
13
  },
14
]);

获取字典数据

1
async function getDictData() {
2
  const res = await dictDataList({
3
    dictType: 'popularization_resource_category',
4
  });
5
  const res2 = await dictDataList({
6
    dictType: 'popularization_resource_tags',
7
  });
8
  let data = res.rows || [];
9
  let data2 = res2.rows || [];
10
  if (data.length) {
11
    data = JSON.parse(
12
      JSON.stringify(data)
13
        .replace(/dictLabel/g, 'label')
14
        .replace(/dictValue/g, 'value'),
15
    );
16
  }
17
  if (data2.length) {
18
    data2 = JSON.parse(
19
      JSON.stringify(data2)
20
        .replace(/dictLabel/g, 'label')
21
        .replace(/dictValue/g, 'value'),
22
    );
23
  }
24
  categoryOptions.value = data as [];
25
  tagOptions.value = data2 as [];
26
}

展开收起

从后端获取资源分类和标签字典数据，将后端返回的 dictLabel 和 dictValue 字段转换为前端组件需要的 label 和 value 格式。

表单初始数据

1
const INITIAL_FORM_DATA = {
2
  id: undefined,
3
  resourceCategory: undefined,
4
  resourceTags: undefined,
5
  resourceType: undefined,
6
  resourceName: undefined,
7
  imageFileId: undefined,
8
  resourceContent: undefined,
9
  resourceFileId: undefined,
10
  imageFileIds: [] as string[],
11
  resourceFileIds: undefined as string[] | undefined,
12
  audioResourceFileIds: undefined as string[] | undefined,
13
  videoResourceFileIds: undefined as string | undefined,
14
};
15
const formData = ref({...INITIAL_FORM_DATA});

展开收起

字段	类型	作用
`id`	number	资源 ID，新增时为 undefined
`resourceCategory`	string	资源分类
`resourceTags`	string[]	资源标签（多选）
`resourceType`	string	资源类型（1-图文，2-音频，3-视频）
`resourceName`	string	资源名称
`imageFileIds`	string[]	封面图片 ID 数组
`resourceContent`	string	图文内容（富文本）
`audioResourceFileIds`	string[]	音频文件 ID 数组
`videoResourceFileIds`	string	视频文件 ID

表单验证规则

1
const formRules = {
2
  resourceName: { required: true, message: '请输入', trigger: 'blur' },
3
  resourceCategory: { required: true, message: '请选择', trigger: 'change' },
4
  resourceTags: { required: true, message: '请选择', trigger: 'change' },
5
  resourceType: { required: true, message: '请选择', trigger: 'change' },
6
  imageFileIds: { required: true, message: '请上传', trigger: 'change' },
7
};

标签解析转换

1
function parseAndConvert(str: string): string[] {
2
  const numArr = JSON.parse(str) as number[];
3
  return Array.isArray(numArr) ? numArr.map((item) => item.toString()) : [];
4
}

将后端返回的标签数组字符串（如 "[1,2,3]"）解析为字符串数组。

初始化表单数据（编辑模式）

1
async function initFormData() {
2
  const id = route.query.id as '';
3
  const resource = await queryPopularizationResourceById(id);
4
  formData.value = resource;
5
  formData.value.resourceTags =
6
    formData.value.resourceTags && parseAndConvert(formData.value.resourceTags);
7
  if (formData.value.imageFileId) {
8
    let params = {
9
      bizId: formData.value.imageFileId,
10
    };
11
    const res = await fileData(params);
12
    formData.value.imageFileIds = res.rows[0].ossId;
13
  }
14
  if (formData.value.resourceFileId) {
15
    let params = {
16
      bizId: formData.value.resourceFileId,
17
    };
18
    const res = await fileData(params);
19
    let tempResourceIds = res.rows?.map((item: any) => {
20
      return item.ossId;
21
    });
22
    if (formData.value.resourceType == '3') {
23
      formData.value.videoResourceFileIds = tempResourceIds?.toString();
24
    }
25
    if (formData.value.resourceType == '2') {
26
      formData.value.audioResourceFileIds = tempResourceIds;
27
    }
28
  }
29
}

展开收起

编辑模式下：

根据 ID 查询资源详情
解析标签数据
根据资源类型处理文件 ID（图片、音频、视频）

表单提交（关键修复点）

1
function handleSubmit() {
2
  formRef.value
3
    .validate()
4
    .then(async () => {
5
      let tags = formData.value.resourceTags || [];
6
      let resourceFileIds = undefined;
7
      if (formData.value.resourceType == '2') {
8
        resourceFileIds = formData.value.audioResourceFileIds;
9
      }
10
      if (formData.value.resourceType == '3') {
11
        resourceFileIds = formData.value.videoResourceFileIds?.length
12
          ? [formData.value.videoResourceFileIds]
13
          : undefined;
14
      }
15
      const allDept = getAllDept();
16
      let params = {
17
        id: formData.value.id,
18
        resourceCategory: formData.value.resourceCategory,
19
        resourceTags: `[${tags.join(',')}]`,
20
        resourceType: formData.value.resourceType,
21
        resourceName: formData.value.resourceName,
22
        resourceContent:
23
          formData.value.resourceType == '1'
24
            ? formData.value.resourceContent
25
            : undefined,
26
        imageFileIds: [formData.value.imageFileIds],
27
        resourceFileIds: resourceFileIds,
28
        audioResourceFileIds: undefined,
29
        videoResourceFileIds: undefined,
30
        sourceDeptId: allDept?.deptId ?? '',
31
        sourceDeptName: allDept?.deptName ?? ''
32
      };
33
      if (params.id) {
34
        //添加异步
35
        await update(params);
36
      } else {
37
        await add(params);
38
      }
39
      handleBack();//添加await后会等待接口响应
40
    })
41
    .catch((error: any) => {
42
      console.log('error', error);
43
    });
44
}

展开收起

问题修复说明：

原来的代码中，add(params) 和 update(params) 没有使用 await，导致：

接口请求还未完成就执行 handleBack()
列表页的 onActivated 钩子触发时，后端数据还未更新
因此列表显示的仍然是旧数据

修复方式：在 add() 和 update() 前添加 await，确保数据写入后端后再返回列表页。

返回列表方法

1
//新增async异步
2
async function handleBack() {
3
  resetForm();
4
  await closeCurrentTab();
5
}

问题说明：

closeCurrentTab() 内部会调用 router.replace() 跳转到前一个标签页
再调用 router.back() 会导致导航冲突，导致 onActivated/onMounted 钩子执行时机异常
因此只保留 closeCurrentTab() 即可

组件挂载

1
onMounted(() => {
2
  const type = route.query.type;
3
  operType.value = type as '';
4
  getDictData();
5
  if (type == 'edit') {
6
    initFormData();
7
  }
8
});

3.3 模板结构#

1
<template>
2
  <Page :auto-content-height="true">
3
    <a-card title="科普资源上传">
4
      <a-form
5
        ref="formRef"
6
        :rules="formRules"
7
        :style="{ width: '80%' }"
8
        :model="formData"
9
        :label-col="{ span: 4 }"
10
        :wrapper-col="{ span: 20 }"
11
        autocomplete="off"
12
      >
13
        <a-form-item label="资源名称" name="resourceName">
14
          <a-input v-model:value="formData.resourceName" placeholder="请输入"></a-input>
15
        </a-form-item>
16
        <a-form-item label="所属分类" name="resourceCategory">
17
          <a-select v-model:value="formData.resourceCategory" :options="categoryOptions" placeholder="请选择"></a-select>
18
        </a-form-item>
19
        <a-form-item label="资源标签" name="resourceTags">
20
          <a-select mode="multiple" v-model:value="formData.resourceTags" :options="tagOptions" placeholder="请选择"></a-select>
21
        </a-form-item>
22
        <a-form-item label="资源类型" name="resourceType">
23
          <a-radio-group v-model:value="formData.resourceType" :options="typeOptions" />
24
        </a-form-item>
25
        <a-form-item label="资源封面" name="imageFileIds">
26
          <ImageUpload :multiple="true" :max-count="1" :max-size="5" accept=".png,.jpg,.svg,.gif" v-model:value="formData.imageFileIds">
27
            <template #helpMessage>
28
              <div class="upload-help-message">支持格式：.png，.jpg，.svg，.gif，单个文件不超过5MB</div>
29
            </template>
30
          </ImageUpload>
31
        </a-form-item>
32
        <a-form-item label="文章正文" name="resourceContent" v-if="formData.resourceType == '1'">
33
          <Tinymce v-model="formData.resourceContent"></Tinymce>
34
        </a-form-item>
35
        <a-form-item label="选择文件" name="resourceFileIds" v-if="formData.resourceType == '2'">
36
          <FileUpload :multiple="true" :max-count="10" :max-size="20" accept=".mp3,.wav,.ogg" v-model:value="formData.audioResourceFileIds">
37
            <template #helpMessage>
38
              <div class="upload-help-message">支持格式：.mp3，.wav，.ogg，限制20MB</div>
39
            </template>
40
          </FileUpload>
41
        </a-form-item>
42
        <a-form-item label="选择文件" name="resourceFileIds" v-if="formData.resourceType == '3'">
43
          <FileUpload :max-count="1" :max-size="100" accept=".mp4,.mov" v-model:value="formData.videoResourceFileIds">
44
            <template #helpMessage>
45
              <div class="upload-help-message">支持格式：.mp4，.mov，限制100MB</div>
46
            </template>
47
          </FileUpload>
48
        </a-form-item>
49
      </a-form>
50
      <div class="form-footer">
51
        <a-button @click="handleBack">取消</a-button>
52
        <a-button type="primary" style="margin-left: 40px !important" @click="handleSubmit">提交</a-button>
53
      </div>
54
    </a-card>
55
  </Page>
56
</template>

展开收起

表单字段	组件	说明
资源名称	`a-input`	文本输入
所属分类	`a-select`	单选下拉
资源标签	`a-select`	多选下拉（`mode="multiple"`）
资源类型	`a-radio-group`	单选按钮组
资源封面	`ImageUpload`	图片上传（最多1张，5MB）
文章正文	`Tinymce`	富文本编辑器（仅图文类型显示）
音频文件	`FileUpload`	音频上传（最多10个，20MB）
视频文件	`FileUpload`	视频上传（最多1个，100MB）

4. data.ts（表格配置）#

4.1 审核状态选项#

1
const statusOptions = reactive([
2
  { value: '', label: '全部' },
3
  { value: '0', label: '待审核' },
4
  { value: '1', label: '已通过' },
5
  { value: '2', label: '退回补正' },
6
]);

4.2 状态值转标签#

1
function getLabelByValue(val: any) {
2
  let item = statusOptions.filter((item) => {
3
    return item.value == val;
4
  })[0];
5
  return item?.label || '';
6
}

根据状态值获取对应的标签文本。

4.3 查询表单配置#

1
export const querySchema: FormSchemaGetter = () => [
2
  {
3
    component: 'Input',
4
    fieldName: 'resourceName',
5
    label: '资源名称',
6
  },
7
  {
8
    component: 'RangePicker',
9
    fieldName: 'uploadTime',
10
    label: '上传时间',
11
  },
12
  {
13
    component: 'Select',
14
    fieldName: 'resourceStatus',
15
    label: '审核状态',
16
    defaultValue: '',
17
    componentProps: {
18
      getPopupContainer,
19
      options: statusOptions,
20
    },
21
  },
22
];

展开收起

4.4 表格列配置#

1
export const columns: VxeGridProps['columns'] = [
2
  { type: 'checkbox', width: 60, align: 'left' },
3
  { title: '资源名称', field: 'resourceName', align: 'left' },
4
  { title: '发布单位', field: 'sourceDeptName', align: 'left', width: 300 },
5
  { title: '上传时间', field: 'uploadTime', align: 'left', width: 200 },
6
  {
7
    title: '审核状态',
8
    field: 'resourceStatus',
9
    align: 'left',
10
    width: 120,
11
    slots: {
12
      default: ({ row }) => {
13
        if (row.resourceStatus) {
14
          return getLabelByValue(row.resourceStatus);
15
        } else {
16
          return '/';
17
        }
18
      },
19
    },
20
  },
21
  {
22
    field: 'action',
23
    fixed: 'right',
24
    width: 'auto',
25
    align: 'left',
26
    slots: { default: 'action' },
27
    title: '操作',
28
    resizable: false,
29
  },
30
];

展开收起

列	字段	说明
复选框	-	用于批量选择
资源名称	`resourceName`	资源标题
发布单位	`sourceDeptName`	上传资源的部门名称
上传时间	`uploadTime`	资源上传时间
审核状态	`resourceStatus`	通过插槽渲染中文标签
操作	`action`	固定在右侧，包含查看和编辑按钮

5. API 文件#

5.1 接口定义#

1
enum Api {
2
  root = '/manager/popularizationResource',
3
  popularizationResourceList = '/manager/popularizationResource/list',
4
  fileData = '/manager/fileData/list',
5
  checkList = 'manager/popularizationApproval/list',
6
}

5.2 接口函数#

函数	方法	路径	说明
`popularizationResourceList`	GET	`/manager/popularizationResource/list`	获取资源列表
`queryPopularizationResourceById`	GET	`/manager/popularizationResource/{id}`	根据 ID 查询资源
`add`	POST	`/manager/popularizationResource`	新增资源
`update`	PUT	`/manager/popularizationResource`	编辑资源
`check`	POST	`/manager/popularizationResource/check`	审核资源
`popularizationResourceDelete`	DELETE	`/manager/popularizationResource/{ids}`	删除资源
`fileData`	GET	`/manager/fileData/list`	获取附件列表

6. 问题修复详解#

6.1 问题一：TypeError - 读取 undefined 的 split#

问题描述

在 system.ts 的 getAllDept 函数中，当 userInfo.allDeptId 或 userInfo.allDeptName 为 undefined 时，调用 .split('/') 会抛出 TypeError。

修复前代码

1
export function getAllDept() {
2
  let dept: any = {};
3
  let userInfo = window.sessionStorage.getItem('userInfo') as any;
4
  if (userInfo) {
5
    userInfo = JSON.parse(userInfo);
6
    dept.deptId = userInfo.allDeptId.split('/')[0];  // 当 allDeptId 为 undefined 时报错
7
    dept.deptName = userInfo.allDeptName.split('/')[0];  // 当 allDeptName 为 undefined 时报错
8
    // ...
9
  }
10
  return dept;
11
}

修复后代码

1
export function getAllDept() {
2
  let dept: any = {};
3
  let userInfo = window.sessionStorage.getItem('userInfo') as any;
4
  if (userInfo) {
5
    userInfo = JSON.parse(userInfo);
6
    //增加空值检查
7
    dept.deptId = (userInfo.allDeptId || '').split('/')[0];
8
    dept.deptName = (userInfo.allDeptName || '').split('/')[0];
9
    if (dept.deptId && dept.deptId.length === 3) {
10
      dept.deptId = Number(dept.deptId);
11
    }
12
  }
13
  return dept;
14
}

修复原理：使用 (userInfo.allDeptId || '') 进行空值判断，当 allDeptId 为 undefined 时，使用空字符串替代，避免调用 split 时报错。

6.2 问题二：新增/编辑后列表不刷新#

问题描述

在 form.vue 的 handleSubmit 函数中，add() 和 update() 没有使用 await，导致表单提交后立即返回列表页，但后端数据还未完成写入，因此列表显示的仍然是旧数据。

修复前代码

1
function handleSubmit() {
2
  formRef.value
3
    .validate()
4
    .then(() => {
5
      // ...构建参数
6
      if (params.id) {
7
        update(params);  // 没有 await，异步操作
8
      } else {
9
        add(params);  // 没有 await，异步操作
10
      }
11
      handleBack();  // 立即返回，不等接口响应
12
    })
13
    // ...
14
}

修复后代码

1
function handleSubmit() {
2
  formRef.value
3
    .validate()
4
    .then(async () => {
5
      // ...构建参数
6
      if (params.id) {
7
        await update(params);  // 等待接口响应
8
      } else {
9
        await add(params);  // 等待接口响应
10
      }
11
      handleBack();  // 数据写入完成后再返回
12
    })
13
    // ...
14
}

修复原理：

在 .then() 回调中添加 async 关键字
在 add() 和 update() 前添加 await，确保接口请求完成后再执行后续操作
返回列表页时，onActivated 钩子触发，调用 tableApi.query() 获取最新数据

配合列表页的刷新机制

列表页通过 onActivated 钩子确保每次回到该页面时都重新查询数据：

1
onActivated(() => {
2
  tableApi.query();
3
});

修复前效果

修复前-列表不刷新

修复后效果

修复后-列表正常刷新

6.3 修复前后对比#

修复前

1
用户点击提交
2
    ↓
3
调用 add(params)（异步，不等待）
4
    ↓
5
立即执行 handleBack()
6
    ↓
7
跳转到列表页
8
    ↓
9
onActivated 触发，查询列表（此时后端数据还未更新）
10
    ↓
11
列表显示旧数据（问题）

修复后

1
用户点击提交
2
    ↓
3
await add(params)（等待接口响应）
4
    ↓
5
后端数据写入完成
6
    ↓
7
执行 handleBack()
8
    ↓
9
跳转到列表页
10
    ↓
11
onActivated 触发，查询列表（此时后端数据已更新）
12
    ↓
13
列表显示新数据（正常）

7. 技术要点#

7.1 异步操作处理#

在处理表单提交时，需要注意异步操作的顺序：

使用 await 确保接口请求完成后再执行后续操作
避免在异步操作未完成时就跳转页面

7.2 空值安全检查#

访问对象属性时，应进行空值检查：

1
// 不安全
2
userInfo.allDeptId.split('/')[0]
3

4
// 安全
5
(userInfo.allDeptId || '').split('/')[0]

7.3 路由导航钩子#

Vue Router 的导航钩子在标签页管理场景中的使用：

onActivated：组件从缓存中激活时触发，适合刷新数据
避免在标签页切换时同时调用 closeCurrentTab() 和 router.back()，会导致导航冲突

7.4 响应式数据管理#

使用 ref 和 reactive 管理表单数据：

ref：用于基本类型和对象，通过 .value 访问
reactive：用于复杂对象，直接访问属性

7.5 表单验证#

Ant Design Vue 表单验证的使用：

通过 ref 获取表单实例
调用 validate() 进行验证
在 .then() 中处理验证通过后的逻辑

8. 总结#

本周修复了两个问题：

通过添加空值检查修复了 getAllDept 函数的 TypeError
通过添加 await 确保异步操作完成后再返回列表页，修复了列表不刷新的问题

修复的核心思路是：

问题一：防御性编程，对可能为 undefined 的值进行空值判断
问题二：正确处理异步操作的执行顺序，确保数据写入完成后再进行页面跳转

后端开发日记⑤：异常工单、退款与重派单

Fri, 10 Jul 2026 00:00:00 GMT

正常订单沿固定路径前进，异常工单则要决定“原订单接下来怎么办”。项目把用户反馈和管理端处置拆开：用户只描述问题，管理端根据实际情况选择关闭、取消退款或生成重派单。

1. 用户提交异常反馈#

提交接口接收订单 ID、异常类型和描述。Service 首先校验参数，再检查订单确实属于当前微信用户：

1
Long wxUserId = SecurityUtils.getUserId();
2
HyDeliveryOrder order = orderMapper.selectById(dto.getOrderId());
3
checkUserOrderOwner(order, wxUserId);

创建人类型、创建人 ID、异常来源、初始严重程度和处理状态全部由后端补充，不能由前端决定。

2. 异常单号表达业务来源#

异常单号按类型使用不同前缀：取消类使用 QX，补发类使用 BF，普通差错使用 CP，后面拼接日期和四位流水号。

单号不仅用于展示，也方便客服看到编号时快速判断大类。不过单号前缀不能代替数据库里的 exceptionType，机器判断仍应使用稳定枚举字段。

3. 三种处置不能强行合并#

直接关闭#

适用于无需改变订单和资金的情况。后端把工单设为 CLOSED，记录关闭结果、处理人和关闭时间，并向原订单追加一条异常处理日志。

取消退款#

这是一个跨表动作：

1
新增退款方向的支付记录
2
  -> 原订单改为 CANCELED
3
  -> 工单改为 COMPLETED
4
  -> 记录 REFUND 过程日志

退款金额默认取订单配送费，也允许管理端传入实际金额。支付方向、渠道、状态和退款原因分别保存，不能只在备注里写“已退款”。

生成重派单#

重派不是修改原订单，而是复制配送所需字段生成新订单，并通过 parentOrderId 关联原订单。新订单直接进入 WAIT_DISPATCH，工单记录 resultOrderId，原订单与新订单各写一条过程日志。

4. 防止重复处置#

工单处于 COMPLETED 或 CLOSED 后不允许再次处理。生成重派单前还要检查 resultOrderId，避免重复点击创建多个子订单。

这些判断必须发生在事务内。单纯依靠前端 loading 或按钮禁用，无法阻止两个并发请求同时到达服务器。

5. 事务为什么重要#

退款和重派都会同时修改多张表。任意一步失败都应该整体回滚：

1
@Transactional(rollbackFor = Exception.class)
2
public HyExceptionTicket refundCancel(...) {
3
    // 支付记录、订单、工单、过程日志
4
}

如果没有事务，可能出现退款记录已生成但订单仍在配送，或者子订单已创建但工单没有关联结果。这样的数据比接口报错更难处理，因为每张表单独看都像是有效记录。

6. 原订单、工单和结果订单#

异常链路最终形成三个角色：

记录	回答的问题
原订单	哪次配送发生了问题
异常工单	问题是什么、由谁处理、处理结果如何
结果订单	是否产生了重派或补发任务

关系字段比把所有信息塞进一张超长备注更适合查询和统计，也方便前端从异常详情跳转到原订单与重派单。

7. 用户反馈方法逐段理解#

用户提交反馈的入口使用事务和同步方法：

1
@Transactional(rollbackFor = Exception.class)
2
public synchronized HyExceptionTicket
3
submitUserExceptionFeedback(UserExceptionFeedbackDto dto) {
4
    if (dto == null || dto.getOrderId() == null) {
5
        throw new ServiceException("订单ID不能为空");
6
    }
7
    String exceptionType = getRequestExceptionType(dto);
8
    if (isBlank(exceptionType)) {
9
        throw new ServiceException("异常类型不能为空");
10
    }
11
    if (isBlank(dto.getDescription())) {
12
        throw new ServiceException("异常描述不能为空");
13
    }
14

15
    Long wxUserId = SecurityUtils.getUserId();
16
    HyDeliveryOrder order = orderMapper.selectById(dto.getOrderId());
17
    checkUserOrderOwner(order, wxUserId);
18
    // 构造并插入工单
19
}

展开收起

getRequestExceptionType 兼容 exceptionType 和旧字段 exceptionFeedback，兼容逻辑集中在 Service 边界，后面的数据库和处置代码始终使用统一值。

synchronized 可以减少单实例内生成相同流水号的概率，但它不是跨节点锁。因此异常单号仍应有数据库唯一索引，并准备好冲突后的重试策略。

8. 异常单号如何解析最大流水#

1
String prefix = getExceptionOrderPrefix(exceptionType);
2
String dateText = DateUtils.dateTime();
3
String maxNo = mapper
4
        .selectMaxExceptionOrderNoByPrefixAndDate(prefix, dateText);
5
int nextSerial = 1;
6
int serialStart = prefix.length() + dateText.length();
7
if (!isBlank(maxNo)
8
        && maxNo.length() >= serialStart + 4) {
9
    nextSerial = Integer.parseInt(
10
            maxNo.substring(serialStart, serialStart + 4)) + 1;
11
}
12
return prefix + dateText
13
        + String.format("%04d", nextSerial);

例如当天已有 CP202608260009，下一张普通差错单就是 CP202608260010。serialStart 根据前缀和日期长度计算，避免在字符串中写死截取位置。

查询最大值再加一仍有并发窗口。更高并发下可以使用数据库序列表、Redis 原子自增或插入冲突后重试，最终都应配合唯一索引。

9. 取消退款代码为什么分成四步#

1
@Transactional(rollbackFor = Exception.class)
2
public HyExceptionTicket refundCancelAdminExceptionTicket(
3
        Long exceptionId,
4
        AdminExceptionTicketActionDto actionDto) {
5
    HyExceptionTicket ticket = getExistingExceptionTicket(exceptionId);
6
    HyDeliveryOrder order = getExistingOrder(ticket.getOrderId());
7
    checkExceptionTicketCanProcess(ticket);
8

9
    BigDecimal amount = actionDto.getRefundAmount() == null
10
            ? defaultAmount(order.getDeliveryFee())
11
            : actionDto.getRefundAmount();
12
    insertCancelRefundPaymentRecord(order, amount, actionDto);
13
    updateDeliveryOrderStatus(order.getOrderId(), "CANCELED");
14
    updateExceptionTicketStatus(
15
            ticket, "COMPLETED", "订单已取消，退款记录已生成", null);
16
    insertAdminOrderProcessLog(
17
            order, "REFUND", "取消退款", "记录退款过程", null);
18
    return mapper.selectById(exceptionId);
19
}

展开收起

先读取工单，再沿 orderId 找到订单，保证处置对象一致。checkExceptionTicketCanProcess 阻止已完成或已关闭工单再次处理。

资金记录用 paymentDirection = OUT 表示支出，订单改为取消，工单记录处理完成，日志留下操作原因。四份数据共同描述一次退款，缺少任何一份都会让对账或详情展示不完整。

10. 重派单为什么复制字段而不是复制对象#

重派单构造时逐项复制配送所需字段：

1
HyDeliveryOrder child = new HyDeliveryOrder();
2
child.setOrderNo(generateDerivedOrderNo("CP"));
3
child.setParentOrderId(source.getOrderId());
4
child.setServiceType(source.getServiceType());
5
child.setWxUserId(source.getWxUserId());
6
child.setTransferPointId(source.getTransferPointId());
7
child.setReceiverName(source.getReceiverName());
8
child.setReceiverPhone(source.getReceiverPhone());
9
child.setShipLongitude(source.getShipLongitude());
10
child.setShipLatitude(source.getShipLatitude());
11
child.setDeliveryFee(source.getDeliveryFee());
12
child.setOrderStatus("WAIT_DISPATCH");
13
child.setVerifyStatus("MANUAL_PASSED");
14
child.setDelFlag("0");

如果直接序列化或反射复制整个对象，原订单主键、当前任务 ID、审核时间、失败状态等字段也可能被带入。白名单复制虽然代码更长，却明确说明哪些业务信息可以继承。

子订单使用新的订单号和主键，通过 parentOrderId 指回原订单。它已经经过人工处置，因此初始状态是待调度、审核状态是人工通过，而不是重新走用户支付流程。

11. resultOrderId 是怎样防重复的#

1
if (ticket.getResultOrderId() != null) {
2
    throw new ServiceException("该异常工单已生成重派单");
3
}

子订单插入成功后，工单保存 resultOrderId。后续请求不仅能判断是否已经重派，也能直接跳转到结果订单。

并发情况下两个请求仍可能同时在检查时看到空值。可以进一步对工单行加锁，或使用条件更新：只有 result_order_id is null 时才能写入。受影响行数为零的请求应回滚自己刚创建的子订单。

12. 事务之外还需要补偿意识#

当前退款记录是本地资金记录，可以和订单事务一起回滚。未来接入真实微信退款后，外部退款成功不能被数据库回滚。

更完整的流程可以拆为：

1
创建本地退款单 PENDING
2
  -> 提交数据库事务
3
  -> 调用支付平台
4
  -> 根据平台结果更新 SUCCESS / FAILED
5
  -> 定时查询长时间 PENDING 的记录

这样外部调用失败不会让订单数据库长事务一直占用连接，也能通过退款单号进行幂等和对账。

13. 本篇小结#

异常处理的核心不是“改成已处理”，而是把处理结果真正落到订单、资金和新配送链路上。明确三种动作、建立父子关系、增加防重复校验并使用事务，才能让异常闭环可追溯。

后端开发日记④：审核、飞行与订单状态流转

Tue, 07 Jul 2026 00:00:00 GMT

管理端订单详情上有多个操作按钮，但后端不能把它们都实现成“接收一个新状态并保存”。状态是业务规则，不是普通字段。本篇记录如何把审核、飞行和送达设计为明确的动作接口。

1. 动作接口代替通用改状态#

管理端提供的核心动作包括：

动作	结果
审核通过	订单进入待调度
审核回退	订单回到可修改、可重提状态
取消订单	订单进入取消终态
开始飞行	关联任务并进入飞行中
确认送达	订单进入已送达终态
标记失败	订单进入失败，并生成异常线索

每个动作都有独立 Service 方法，例如 approveAdminDeliveryOrder、startFlightAdminDeliveryOrder。接口只接受动作需要的参数，前端无法随意把订单从待支付直接改成已送达。

2. 当前实现先确认订单，再由动作决定目标状态#

每个动作都会先读取最新订单并确认记录存在：

1
HyDeliveryOrder order = getExistingAdminOrder(orderId);
2
updateAdminOrderStatus(
3
        order, "WAIT_DISPATCH", "MANUAL_PASSED",
4
        "", "", null);

目标状态由 approveAdminDeliveryOrder 等后端方法写死，前端不能在请求体中自由传入任意状态，这是动作接口已经建立的第一层边界。

不过当前 updateAdminOrderStatus 主要负责写入字段，还没有完整校验每个动作允许的来源状态。也就是说，若有人绕过页面直接调用“确认送达”接口，仅靠按钮隐藏并不足以阻止非法跳转。本文后面的条件更新部分会继续说明如何补上这层校验。

3. 审核通过与审核回退#

审核通过会记录审核人、审核时间和审核意见，并把订单送入待调度阶段。审核回退除了写入原因，还要保留订单原有资料，让小程序用户能够修改后重新提交。

审核结果不是一段备注，而是一条可追踪的业务事件，因此同时写入过程日志：

1
processType: AUDIT
2
processTitle: 审核通过 / 审核回退
3
operatorType: SYS_USER
4
operatorId: 当前管理员
5
operationReason: 审核意见

4. 开始飞行先建立任务关系#

订单进入飞行中之前，需要确认飞行任务存在，并把 currentTaskId 与订单关联。这样详情页、轨迹接口和过程日志都能沿同一个任务 ID 找到数据。

如果先改订单状态、后建飞行任务，中途失败就会出现“显示飞行中却没有任务”的记录。正确顺序和事务边界应该共同保证两者一致。

5. 成功和失败都是终态，但含义不同#

确认送达会记录实际送达时间，订单进入正常终态。标记配送失败除了更新订单，还要保存失败原因，并按业务需要衔接异常工单。

规则上，终态操作尤其需要防重复：

已送达订单不能再次开始飞行；
已取消订单不能再次审核；
已失败订单不能被普通更新接口改回进行中；
重复确认送达不能生成多条互相冲突的日志。

6. 进度不是直接翻译状态#

用户订单进度由过程日志整理而来，而不是只根据当前状态猜测。当前状态回答“现在怎样”，日志回答“怎么走到这里”。两者分开后，可以同时展示下单、支付、审核、调度、飞行与完成等历史节点。

管理端还能查看更完整的操作原因，用户端则返回经过整理的 UserOrderProgressVo，避免暴露内部备注和管理员信息。

7. Action DTO 为什么比直接传实体更合适#

管理端动作使用 AdminDeliveryOrderActionDto 接收审核意见、操作原因、任务信息和异常类型。它的作用不是把所有字段都变成可选，而是让一次动作只携带必要上下文。

审核通过的 Service 代码很短：

1
@Transactional(rollbackFor = Exception.class)
2
public HyDeliveryOrder approveAdminDeliveryOrder(
3
        Long orderId,
4
        AdminDeliveryOrderActionDto actionDto) {
5
    AdminDeliveryOrderActionDto action = safeAction(actionDto);
6
    HyDeliveryOrder order = getExistingAdminOrder(orderId);
7
    updateAdminOrderStatus(
8
            order, "WAIT_DISPATCH", "MANUAL_PASSED",
9
            "", "", null);
10
    insertAdminOrderProcessLog(
11
            order, "AUDIT", "审核通过",
12
            defaultIfBlank(action.getProcessContent(),
13
                    "管理员审核通过，订单进入待配送状态"),
14
            action.getOperationReason());
15
    return mapper.selectById(orderId);
16
}

展开收起

safeAction 把空请求体转换为空 DTO，后续可以统一使用默认文案。getExistingAdminOrder 负责订单存在性，updateAdminOrderStatus 统一写状态与审核字段，最后重新查询数据库，保证返回值包含实际持久化结果。

如果直接接收 HyDeliveryOrder，前端就可能同时提交费用、用户 ID、删除标记等与审核无关的字段，接口边界会变得模糊。

8. 审核回退如何组织原因#

回退动作需要同时保存机器状态和人工说明：

1
String rejectReason = defaultIfBlank(
2
        action.getRejectReason(), action.getOperationReason());
3
String rejectExplain = defaultIfBlank(
4
        action.getRejectExplain(), action.getProcessContent());
5

6
boolean changed = updateAdminOrderStatus(
7
        order, "REJECTED", null,
8
        rejectReason, rejectExplain, null);
9
insertAdminOrderProcessLog(
10
        order, "AUDIT", "审核回退",
11
        defaultIfBlank(action.getProcessContent(),
12
                "管理员审核回退，订单需要用户修改后重新提交"),
13
        rejectReason);
14
if (changed) {
15
    insertOrderStatusNotification(order, "REJECTED");
16
}

展开收起

rejectReason 适合保存结构化或短原因，rejectExplain 保存给用户看的补充说明，过程日志则保留这次操作的时间线内容。

updateAdminOrderStatus 返回是否真正发生状态变化。只有第一次从其他状态进入 REJECTED 时才新增通知，重复请求不会不断制造相同消息。

9. 开始飞行的代码顺序#

1
HyDeliveryOrder order = getExistingAdminOrder(orderId);
2
HyFlightTask task = saveAdminFlightTask(order, action);
3
updateAdminOrderStatus(
4
        order, "DELIVERING", null,
5
        null, null, task.getId());
6
order.setCurrentTaskId(task.getId());
7
insertAdminOrderProcessLog(
8
        order, "FLIGHT_REGISTER", "开始飞行",
9
        "管理员登记开始飞行，订单进入配送中",
10
        action.getOperationReason());

先保存飞行任务，得到本地主键以后再写入订单 currentTaskId。过程日志使用更新后的任务 ID，因此三张表可以沿同一个 ID 建立关系。

这些步骤处在事务中，本地数据库失败时可以一起回滚。不过如果 saveAdminFlightTask 内部已经成功调用真实设备平台，数据库事务无法撤销外部动作。因此外部任务最好使用稳定请求号，并在失败后查询第三方实际状态，而不是简单重发。

10. 确认送达为什么只在首次变化时发消息#

1
updateAdminFlightArriveTime(order.getCurrentTaskId(), action);
2
boolean changed = updateAdminOrderStatus(
3
        order, "COMPLETED", null, null, null, null);
4
insertAdminOrderProcessLog(
5
        order, "ARRIVED", "确认送达",
6
        "管理员确认订单已送达",
7
        action.getOperationReason());
8
if (changed) {
9
    insertOrderDeliveredNotification(order);
10
    sendOrderArrivedWechatMessage(order);
11
}

站内通知和微信推送都具有外部可见副作用。将它们放在 changed 分支，可以阻止管理员重复点击时重复提醒用户。

过程日志是否也要防重复，需要按审计要求决定。若每次请求都写日志，可以记录重复操作；若时间线只展示业务节点，则应为日志增加唯一约束或同样受状态变化控制。

11. 配送失败会衍生新业务#

失败动作并不只是把状态改成 DELIVERY_FAILED：

1
boolean changed = updateAdminOrderStatus(
2
        order, "DELIVERY_FAILED", null,
3
        null, null, null);
4
insertAdminOrderProcessLog(
5
        order, "DELIVERY_FAILED", "配送失败",
6
        action.getProcessContent(),
7
        action.getOperationReason());
8
if (changed) {
9
    insertDeliveryFailedExceptionTicket(order, action);
10
    insertOrderStatusNotification(order, "DELIVERY_FAILED");
11
}

异常类型在创建工单前必须校验，因为后续统计会按类型聚合失败原因。若只把失败原因写在自由文本里，报表无法稳定统计“天气突变”和“设备低电量”等分类。

12. 并发更新还可以怎样加强#

当前 Service 会先查询再更新，适合表达业务规则，但两个管理员同时操作仍可能读到相同旧状态。进一步可以使用条件更新：

1
update hy_delivery_order
2
set order_status = 'DELIVERING',
3
    current_task_id = #{taskId}
4
where order_id = #{orderId}
5
  and order_status = 'WAIT_DISPATCH'

如果受影响行数为 0，说明订单已被其他请求处理，应重新查询并返回明确提示。也可以增加版本号实现乐观锁。状态检查和条件更新结合后，业务提示清晰，数据库也能在最后一步阻止并发覆盖。

13. 本篇小结#

状态机的价值是把不允许发生的跳转挡在 Service 层。为每个业务动作建立明确入口，再把状态、关联任务和过程日志放进同一事务，订单流程才不会因为重复请求或局部失败变得不可解释。

实习笔记①

Tue, 07 Jul 2026 00:00:00 GMT

领导安排的练手工作，根据页面原型图编写前端页面并对后端接口进行调用。

1. 添加”换届任免名单”模块#

在管理功能菜单列表中添加”换届任免名单”模块并配置 icon 图标。

菜单配置#

1
const menuList = [
2
  ...,
3
  {
4
    id: 9,
5
    title: '换届任免名单',
6
    icon: 'icon-wenjian',
7
    iconColor: '#722ED1',
8
    bgColor: '#F9F0FF',
9
    path: '/workbench/appointment/index',
10
    isIconfont: true,
11
  }
12
]

菜单渲染#

1
<div class="menu-grid">
2
  <div class="menu-item" v-for="item in menuList" :key="item.id" @click="goToMenu(item)">
3
    <div class="menu-icon" :style="{ backgroundColor: item.bgColor }">
4
      <van-icon v-if="!item.isIconfont" :name="item.icon" :color="item.iconColor" size="24" />
5
      <i v-else class="iconfont" :class="item.icon" :style="{ color: item.iconColor, fontSize: '24px' }"></i>
6
    </div>
7
    <span class="menu-title">{{ item.title }}</span>
8
  </div>
9
</div>

通过 v-for 遍历 menuList 数组，根据 item.isIconfont 判断使用 vant 图标还是 iconfont 图标。

页面效果图#

换届任免名单模块

2. 配置路由#

在项目路由配置中添加”换届任免名单”相关路由。

1
{
2
  path: '/workbench',
3
  name: 'workbench',
4
  meta: { title: '工作台' },
5
  redirect: '/workbench/notice/index',
6
  children: [
7
    // ...其他路由
8
    { path: 'appointment/index', name: 'workbenchAppointmentIndex', component: () => import('@/views/workbench/appointment/index.vue'), meta: { title: '换届任免名单' } },
9
    { path: 'appointment/positions', name: 'workbenchAppointmentPositions', component: () => import('@/views/workbench/appointment/positions.vue'), meta: { title: '职位分类' } },
10
    { path: 'appointment/detail', name: 'workbenchAppointmentDetail', component: () => import('@/views/workbench/appointment/detail.vue'), meta: { title: '任免详情' } }
11
  ]
12
}

3. 页面实现详解#

3.1 index.vue（换届任免列表页）#

页面功能#

展示换届任免名单列表，支持下拉刷新和上拉加载更多，点击列表项跳转到职位分类页。

代码实现#

导入模块

1
import { appointmentList } from '@/api/workbench.js'
2
import { reactive, ref } from 'vue'
3
import { useRouter } from 'vue-router'

appointmentList：获取任免列表的 API 接口
reactive、ref：Vue 3 响应式数据 API
useRouter：Vue Router 路由钩子

定义响应式变量

1
const router = useRouter()
2
const dataList = ref([])
3
const loading = ref(false)
4
const finished = ref(false)
5
const refreshing = ref(false)

变量名	类型	作用
`router`	Router	路由实例，用于页面跳转
`dataList`	ref	存储任免列表数据
`loading`	ref	控制列表加载状态
`finished`	ref	标记是否已加载全部数据
`refreshing`	ref	控制下拉刷新状态

定义请求参数

1
const params = reactive({
2
  pageNum: 1,
3
  pageSize: 10,
4
  id: '',
5
  title: '',
6
  congressInfoId: ''
7
})

参数名	类型	作用
`pageNum`	number	当前页码，用于分页
`pageSize`	number	每页条数，默认 10
`id`	string	任免 ID，用于精确查询
`title`	string	任免标题，用于模糊搜索
`congressInfoId`	string	会议信息 ID，用于筛选

加载数据方法

1
const loadData = async () => {
2
  if (finished.value) return
3

4
  try {
5
    const { rows = [], total = 0 } = await appointmentList(params)
6

7
    dataList.value.push(...rows)
8
    params.pageNum += 1
9
    finished.value = dataList.value.length >= total || rows.length < params.pageSize
10
  } catch (error) {
11
    console.error('加载换届任免信息失败', error)
12
  } finally {
13
    loading.value = false
14
    refreshing.value = false
15
  }
16
}

展开收起

检查 finished 状态，避免重复加载
调用 appointmentList 接口获取数据
将新数据追加到 dataList 中，实现滚动加载
更新页码，并判断是否已加载全部数据

下拉刷新方法

1
const onRefresh = () => {
2
  params.pageNum = 1
3
  dataList.value = []
4
  finished.value = false
5
  loading.value = true
6
  loadData()
7
}

重置页码为 1
清空列表数据
重置加载状态
重新加载数据

跳转详情方法

1
const goToDetail = (item) => {
2
  router.push({
3
    path: '/workbench/appointment/positions',
4
    query: {
5
      id: item.id,
6
      title: item.title
7
    }
8
  })
9
}

跳转到职位分类页
通过 query 参数传递任免 ID 和标题

日期格式化方法

1
const formatDate = (dateStr) => {
2
  if (!dateStr) return '-'
3
  return String(dateStr).slice(0, 10)
4
}

将日期字符串截取为 YYYY-MM-DD 格式

会议届数格式化方法

1
const formatSession = (congressInfoId) => {
2
  if (congressInfoId === null || congressInfoId === undefined || congressInfoId === '') {
3
    return '换届任免'
4
  }
5
  return `第${congressInfoId}届`
6
}

根据 congressInfoId 显示会议届数，为空时显示默认文本

模板结构#

1
<div class="page">
2
  <div class="content">
3
    <van-pull-refresh v-model="refreshing" class="refresh-wrap" @refresh="onRefresh">
4
      <van-list v-model:loading="loading" :finished="finished" finished-text="已经到底了" :immediate-check="true" @load="loadData">
5
        <div class="list-wrap">
6
          <button v-for="item in dataList" :key="item.id" type="button" class="info-card" @click="goToDetail(item)">
7
            <div class="icon-wrapper" aria-hidden="true">
8
              <van-icon name="description" size="24" color="#1683ff" />
9
            </div>
10
            <div class="card-content">
11
              <div class="title">{{ item.title || '未命名换届任免信息' }}</div>
12
              <div class="subtitle" v-if="item.congressInfoId">第{{ item.congressInfoId }}次代表大会</div>
13
              <div class="session-tag">{{ formatSession(item.congressInfoId) }}</div>
14
              <div class="publish-date">发布日期：{{ formatDate(item.createTime) }}</div>
15
            </div>
16
          </button>
17
          <van-empty v-if="finished && dataList.length === 0" image="search" description="暂无任免信息" />
18
        </div>
19
      </van-list>
20
    </van-pull-refresh>
21
  </div>
22
  <div class="footer-space"></div>
23
</div>

展开收起

组件	作用
`van-pull-refresh`	下拉刷新组件，包裹整个列表
`van-list`	列表组件，支持滚动加载更多
`van-empty`	空状态组件，列表为空时显示
`van-icon`	图标组件，显示文档图标

样式设计#

1
.page {
2
  width: 100%;
3
  min-height: 100%;
4
  display: flex;
5
  flex-direction: column;
6
  overflow: hidden;
7
  background: #f4f7fd;
8
}
9

10
.content {
11
  flex: 1;
12
  overflow-y: auto;
13
  -webkit-overflow-scrolling: touch;
14
}
15

16
.footer-space {
17
  height: 66px;
18
  background: #fff;
19
}
20

21
.info-card {
22
  width: 100%;
23
  min-height: 124px;
24
  display: flex;
25
  align-items: flex-start;
26
  gap: 14px;
27
  margin: 0 0 14px;
28
  padding: 20px;
29
  border: 0;
30
  border-radius: 18px;
31
  background: #fff;
32
  box-shadow: 0 5px 14px rgba(50, 104, 170, 0.04);
33
  cursor: pointer;
34
  transition: opacity 0.15s ease, transform 0.15s ease;
35

36
  &:active {
37
    opacity: 0.88;
38
    transform: scale(0.99);
39
  }
40
}

展开收起

使用 Flexbox 布局实现响应式页面结构
footer-space 预留底部导航栏空间
卡片式设计，带有阴影和圆角
点击时有缩放和透明度变化的交互反馈

页面效果图#

换届任免列表页

3.2 positions.vue（职位分类页）#

页面功能#

展示职位分类列表，点击职位跳转到任免详情页。

代码实现#

导入模块

1
import { onMounted, reactive, ref } from 'vue'
2
import { useRouter, useRoute } from 'vue-router'
3
import { showToast } from 'vant'

onMounted：组件挂载生命周期钩子
useRoute：获取当前路由信息

定义变量

1
const router = useRouter()
2
const route = useRoute()
3

4
const positions = reactive([
5
  { id: 'chairman', name: '主席' },
6
  { id: 'viceChairman', name: '副主席' },
7
  { id: 'standingCommittee', name: '常委会' },
8
  { id: 'committee', name: '委员会' },
9
  { id: 'assistant', name: '助会负责人' }
10
])

职位 ID	职位名称
`chairman`	主席
`viceChairman`	副主席
`standingCommittee`	常委会
`committee`	委员会
`assistant`	助会负责人

跳转详情方法

1
const goToDetail = (position) => {
2
  router.push({
3
    path: '/workbench/appointment/detail',
4
    query: {
5
      appointmentId: route.query.id,
6
      positionId: position.id,
7
      positionName: position.name,
8
      title: route.query.title
9
    }
10
  })
11
}

跳转到任免详情页
传递任免 ID、职位 ID、职位名称和标题

模板结构#

1
<div class="page">
2
  <div class="content">
3
    <div class="positions-container">
4
      <div class="position-item" v-for="item in positions" :key="item.id" @click="goToDetail(item)">
5
        <span class="position-name">{{ item.name }}</span>
6
        <van-icon name="arrow" color="#ccc" size="16" />
7
      </div>
8
    </div>
9
  </div>
10
  <div class="footer-space"></div>
11
</div>

使用 v-for 遍历职位列表
每个职位项显示职位名称和箭头图标

样式设计#

1
.position-item {
2
  display: flex;
3
  border-radius: 12px;
4
  align-items: center;
5
  justify-content: space-between;
6
  padding: 18px 20px;
7
  margin-bottom: 12px;
8
  background: #fff;
9
  box-shadow: 0 5px 14px rgba(50, 104, 170, 0.04);
10
  transition: opacity 0.15s ease, transform 0.15s ease;
11

12
  &:last-child {
13
    margin-bottom: 0;
14
  }
15

16
  &:active {
17
    opacity: 0.88;
18
    transform: scale(0.99);
19
  }
20
}

展开收起

列表项使用圆角卡片设计
左侧显示职位名称，右侧显示箭头图标
点击时有缩放和透明度变化的交互反馈

页面效果图#

职位分类页

3.3 detail.vue（任免详情页）#

页面功能#

展示任免详情信息，包括标题、发布时间和富文本内容。

代码实现#

导入模块

1
import { onMounted, reactive } from 'vue'
2
import { useRoute } from 'vue-router'
3
import { showToast, showLoadingToast, closeToast } from 'vant'
4
import { appointmentDetail } from '@/api/workbench.js'

showLoadingToast、closeToast：vant 加载提示组件
appointmentDetail：获取任免详情的 API 接口

定义响应式变量

1
const route = useRoute()
2

3
const detail = reactive({
4
  title: '',
5
  publishDate: '',
6
  createTime: '',
7
  content: ''
8
})

字段	类型	作用
`title`	string	任免标题
`publishDate`	string	发布日期
`createTime`	string	创建时间
`content`	string	任免内容（HTML 格式）

安全渲染 HTML 方法

1
const safeHtml = (html) => {
2
  if (!html) return ''
3
  return html
4
    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
5
    .replace(/<iframe[^>]*>[\s\S]*?<\/iframe>/gi, '')
6
    .replace(/on\w+="[^"]*"/gi, '')
7
}

过滤 HTML 中的 <script> 标签，防止 XSS 攻击
过滤 <iframe> 标签，防止嵌入恶意页面
过滤 on* 事件属性，防止事件注入攻击

日期格式化方法

1
const formatDate = (dateStr) => {
2
  if (!dateStr) return ''
3
  const match = dateStr.match(/^\d{4}-\d{2}-\d{2}/)
4
  return match ? match[0] : dateStr
5
}

使用正则表达式提取日期部分
支持多种日期格式输入

加载详情方法

1
const loadDetail = async () => {
2
  showLoadingToast({ message: '加载中...', forbidClick: true, duration: 0 })
3

4
  try {
5
    const res = await appointmentDetail(route.query.appointmentId)
6
    const detailData = res?.data || res
7

8
    if (res?.code === 200 && detailData) {
9
      Object.assign(detail, detailData)
10
      detail.content = safeHtml(detail.content)
11
    } else {
12
      showToast(res?.msg || '暂无数据')
13
    }
14
  } catch (error) {
15
    console.error('获取任免详情失败:', error)
16
    showToast('获取数据失败')
17
  } finally {
18
    closeToast()
19
  }
20
}

展开收起

显示加载提示，禁止点击
调用 appointmentDetail 接口获取详情
使用 safeHtml 处理内容，防止 XSS 攻击
根据接口返回码判断是否成功
无论成功或失败，都关闭加载提示

组件挂载

1
onMounted(() => {
2
  loadDetail()
3
})

组件挂载时自动加载任免详情

模板结构#

1
<div class="page">
2
  <div class="content">
3
    <div class="detail-card">
4
      <div class="detail-title">{{ route.query.title || detail.title || '-' }}</div>
5
      <div class="detail-date">发布时间：{{ formatDate(detail.publishDate) || formatDate(detail.createTime) || '-' }}</div>
6
      <div class="detail-content rich-text" v-html="detail.content || ''"></div>
7
    </div>
8
  </div>
9
  <div class="footer-space"></div>
10
</div>

部分	作用
`detail-title`	显示任免标题，优先使用路由参数中的标题
`detail-date`	显示发布时间，优先使用 `publishDate`，其次使用 `createTime`
`detail-content`	使用 `v-html` 渲染富文本内容

样式设计#

1
.detail-card {
2
  background: #fff;
3
  border-radius: 18px;
4
  padding: 20px;
5
  border: 1px solid rgba(0, 0, 0, 0.04);
6
}
7

8
.detail-title {
9
  font-size: 18px;
10
  font-weight: 700;
11
  color: #333;
12
  line-height: 1.5;
13
  margin-bottom: 12px;
14
  text-align: center;
15
}
16

17
.detail-date {
18
  font-size: 13px;
19
  color: #999;
20
  margin-bottom: 20px;
21
  padding-bottom: 12px;
22
  border-bottom: 1px solid #f4f5fa;
23
  text-align: center;
24
}
25

26
.detail-content {
27
  color: #333;
28
  font-size: 15px;
29
  line-height: 2;
30
}
31

32
.rich-text {
33
  :deep(p) {
34
    margin: 0 0 16px;
35
    line-height: 2;
36
  }
37

38
  :deep(ul),
39
  :deep(ol) {
40
    padding-left: 22px;
41
    margin: 16px 0;
42
  }
43

44
  :deep(img) {
45
    max-width: 100%;
46
    height: auto;
47
  }
48
}

展开收起

卡片式布局，带有圆角和边框
标题居中显示，使用粗体字
发布时间下方有分隔线
富文本内容支持段落、列表和图片

页面效果图#

任免详情页

4. 页面流程总结#

1
index.vue（任免列表）
2
    ↓ 点击列表项
3
positions.vue（职位分类）
4
    ↓ 点击职位项
5
detail.vue（任免详情）

页面	路由路径	功能
index.vue	`/workbench/appointment/index`	展示任免列表，支持分页加载
positions.vue	`/workbench/appointment/positions`	展示职位分类，选择具体职位
detail.vue	`/workbench/appointment/detail`	展示任免详情，渲染富文本内容

5. 技术要点#

5.1 响应式数据管理#

使用 Vue 3 Composition API 中的 ref 和 reactive 管理响应式数据：

ref：用于基本类型数据（字符串、数字、布尔值）
reactive：用于对象类型数据

5.2 分页加载实现#

通过 van-list 组件实现滚动加载：

loading：控制加载状态
finished：标记是否已加载全部数据
pageNum：当前页码，每次加载后递增

5.3 XSS 防护#

在渲染富文本内容时，使用 safeHtml 方法过滤危险标签和属性：

移除 <script> 标签
移除 <iframe> 标签
移除 on* 事件属性

5.4 路由参数传递#

通过 router.push 的 query 参数传递数据：

使用 route.query 获取参数
参数包括：任免 ID、职位 ID、职位名称、标题

5.5 移动端适配#

使用 Flexbox 布局和响应式设计：

overflow-y: auto 实现内容滚动
-webkit-overflow-scrolling: touch 优化 iOS 滚动体验
footer-space 预留底部导航栏空间

后端开发日记③：订单创建、模拟支付与重新提交

Sat, 04 Jul 2026 00:00:00 GMT

配送订单是整个系统的主线。前端看到的是“提交表单”，后端却要同时处理订单号、服务类型、初始状态、支付记录、过程日志、历史版本和用户归属。本篇先记录用户侧从创建到进入审核的链路。

1. 两类订单共用主表#

快递和外卖共享收货人、船舶、接驳点、坐标与费用等字段，差异字段则按服务类型填写：

服务类型	业务前缀	主要差异字段
`TAKEOUT`	`WM`	平台名称、平台订单号、骑手电话
`EXPRESS`	`KD`	快递公司、快递单号

Service 会先校验服务类型，再只接受对应业务需要的字段，避免一条记录同时出现外卖平台和快递公司的矛盾数据。

2. 订单号由后端生成#

订单号由“业务前缀 + 日期 + 当日四位流水号”组成。后端按当天前缀查询最大订单号，再生成下一序号：

1
WM202608240001
2
KD202608240001

订单号属于业务事实，不能依赖前端生成。当前实现通过同步方法缩小同一实例内的并发窗口，数据库还应使用唯一索引作为最后一道约束。

3. 创建订单不是只插一张表#

创建操作位于事务中，至少完成三件事：

从 SecurityUtils 取得当前微信用户并写入 wxUserId；
保存订单主记录，设置删除标记、操作人类型和初始状态；
写入 CREATE_ORDER 过程日志，让进度页有第一条可追踪记录。

DTO 只承载用户能够填写的内容，订单状态、审核状态、用户 ID 等字段由后端决定，避免越权赋值。

4. 模拟支付也要保存支付事实#

项目暂未接入真实支付，因此提供模拟支付接口，但后端仍按正式流程建模。支付时先检查订单归属与当前状态，再写入 HyOrderPaymentRecord，随后更新订单状态并增加 PAY 流程日志。

1
订单状态校验
2
  -> 新增支付记录
3
  -> 更新订单状态
4
  -> 新增过程日志

这些操作必须在同一事务内完成。否则可能出现“支付记录成功但订单仍待支付”，或者“订单已支付却没有账务记录”的不一致。

5. 修改与历史快照#

订单被修改前会保存历史快照。快照不是简单复制一份无意义的数据，而是为凭证版本、驳回重提和管理端追溯提供依据。

用户修改订单时需要同时满足：

订单属于当前登录用户；
订单未被逻辑删除；
当前状态允许编辑；
请求只更新用户端允许维护的字段。

配送凭证会记录上传时对应的订单版本，因此查看历史订单时可以知道图片属于哪次提交。

6. 驳回后的重新提交#

审核驳回不是创建新订单，而是在保留历史的前提下修正原订单。重新提交会保存旧版本、应用新的业务字段、重置审核相关状态，并写入 RESUBMIT_AUDIT 日志。

这样既保持订单号连续，也保留了“为什么修改、修改前是什么”的审计线索。

7. 超时未支付自动取消#

定时任务调用 cancelTimeoutUnpaidOrders(15) 处理超过 15 分钟仍未支付的订单。批量更新状态之外，还要为每个订单补充 PAYMENT_TIMEOUT_CANCEL 日志，用户才能在进度中理解订单为什么结束。

定时任务只负责触发，具体判断仍放在订单 Service 中。这样人工调用、调度调用和后续补偿任务可以复用同一规则。

8. 创建方法逐行拆解#

创建订单的核心方法没有直接保存 DTO：

1
@Transactional(rollbackFor = Exception.class)
2
public HyDeliveryOrder createUserDeliveryOrder(
3
        UserDeliveryOrderCreateDto createDto) {
4
    if (createDto == null) {
5
        throw new ServiceException("订单参数不能为空");
6
    }
7
    if (isBlank(createDto.getServiceType())) {
8
        throw new ServiceException("服务类型不能为空");
9
    }
10
    checkUserOrderRequired(createDto);
11

12
    HyDeliveryOrder order = buildUserDeliveryOrder(createDto);
13
    deliveryOrderMapper.insertHyDeliveryOrder(order);
14
    insertUserOrderProcessLog(
15
            order, PROCESS_TYPE_CREATE_ORDER,
16
            "用户下单", "用户提交订单，订单进入待支付状态");
17
    return order;
18
}

展开收起

第一层校验处理对象和关键枚举为空，checkUserOrderRequired 再根据快递或外卖检查差异字段。两种校验分开后，错误信息可以更具体，也避免构造实体后才发现缺少必要数据。

buildUserDeliveryOrder 负责生成订单号、写入当前用户 ID、设置初始 UNPAID 状态和系统字段。insertHyDeliveryOrder 使用数据库生成的主键回填 orderId，后面的过程日志才能正确关联订单。

最后两次插入处在同一个事务中。如果日志插入失败，订单也会回滚，不会出现进度页找不到创建节点的半成品记录。

9. 支付方法为什么先判断超时#

模拟支付的关键顺序是：

1
HyDeliveryOrder order = mapper.selectById(orderId);
2
checkUserOrderOwner(order, currentUserId);
3

4
if (!"UNPAID".equals(order.getOrderStatus())) {
5
    return order;
6
}
7

8
Date payTime = DateUtils.getNowDate();
9
if (isPaymentTimeout(order, 15, payTime)) {
10
    cancelTimeoutUnpaidOrder(order, payTime, 15);
11
    return mapper.selectById(orderId);
12
}
13

14
insertSuccessPaymentRecord(order, payTime);
15
updateOrderStatus(orderId, "PENDING_AUDIT");
16
insertUserOrderProcessLog(order, "PAY", "支付成功", ...);

展开收起

顺序不能改成“先支付成功，再判断创建时间”。用户在第 16 分钟点击支付时，定时任务可能还没有扫描到该订单，但业务上它已经超时，所以支付接口自身也必须执行同样的超时规则。

当订单已经不是 UNPAID 时直接返回最新订单，体现了基础幂等性：重复点击不会再次新增支付流水。更严格的真实支付还需要支付平台流水号唯一索引和回调幂等表。

10. 支付流水字段表达什么#

支付成功记录的构造如下：

1
HyOrderPaymentRecord payment = new HyOrderPaymentRecord();
2
payment.setOrderId(order.getOrderId());
3
payment.setWxUserId(order.getWxUserId());
4
payment.setPaymentType("ORDER_INCOME");
5
payment.setPaymentDirection("IN");
6
payment.setPaymentAmount(
7
        defaultDecimal(order.getDeliveryFee()));
8
payment.setPaymentStatus("SUCCESS");
9
payment.setPayChannel("OTHER");
10
payment.setCreateTime(payTime);

paymentType 说明为什么产生资金变化，paymentDirection 说明资金方向，paymentStatus 说明当前结果。三者不能合并成一个“已支付”字段，因为后续还有取消退款、退款处理中和失败等情况。

配送费为空时归一化为零，而不是把 null 写入金额字段。真正接入支付平台后，金额还要以最小货币单位或固定精度类型传输，不能使用浮点数。

11. 修改订单先保存哪个版本#

修改方法先读取数据库中的旧订单，然后计算版本号并写历史：

1
Long oldVersionNo = getCurrentOrderVersionNo(
2
        existOrder.getOrderId());
3
HyDeliveryOrderHistory history = buildOrderHistory(
4
        existOrder, oldVersionNo,
5
        "用户修改订单基础信息", wxUserId);
6
historyMapper.insertHyDeliveryOrderHistory(history);
7

8
HyDeliveryOrder update = buildUserDeliveryOrderUpdate(
9
        updateDto, existOrder);
10
deliveryOrderMapper.updateHyDeliveryOrder(update);

历史表保存的是“修改前”而不是“修改后”。如果先更新主表再复制，快照和当前记录会完全相同，失去审计意义。

这里还把 updateDto.serviceType 强制设为原订单类型。快递订单不能通过修改接口变成外卖订单，因为两种订单的单号前缀、差异字段和校验规则已经在创建时确定。

12. 重新提交如何防止重复#

重新提交前先处理两个状态：

1
if ("PENDING_AUDIT".equals(order.getOrderStatus())) {
2
    return order;
3
}
4
if (!isRejectedOrder(order.getOrderStatus())) {
5
    throw new ServiceException(
6
            "当前订单状态不允许重新提交审核");
7
}

第一个分支让重复请求获得相同结果，第二个分支阻止从待支付、配送中或终态跳到待审核。通过后才保存历史、更新业务字段、清空驳回原因并写 RESUBMIT_AUDIT 日志。

这类“重复时返回成功结果，非法路径时明确报错”的区分很有用。重复请求属于网络和交互中可能出现的正常情况，非法状态跳转则说明调用方逻辑有问题。

13. 定时取消为什么仍要逐单处理#

任务先按截止时间查询所有超时未支付订单：

1
Date deadline = DateUtils.addMinutes(now, -timeoutMinutes);
2
List<HyDeliveryOrder> rows =
3
        mapper.selectTimeoutUnpaidOrderList(deadline);
4
for (HyDeliveryOrder row : rows) {
5
    if (cancelTimeoutUnpaidOrder(row, now, timeoutMinutes)) {
6
        canceledCount++;
7
    }
8
}

直接一条 SQL 批量改状态虽然更快，却不容易为每笔订单生成过程日志、通知和取消原因。当前逐单处理优先保证业务记录完整。

数据量变大后，可以分页扫描或按主键分批，避免一个大事务锁住过多记录；还可以用条件更新再次限制 order_status = 'UNPAID'，防止扫描后用户刚好完成支付造成竞态。

14. 本篇小结#

订单创建的重点不在 CRUD，而在一次动作留下完整事实：谁创建、当前处于什么状态、支付是否发生、修改过几次、为什么进入下一阶段。把这些信息拆成订单、支付记录、历史快照和过程日志以后，后续审核、飞行和异常处置才能可靠衔接。

后端开发日记②：微信登录、用户资料与地址归属

Wed, 01 Jul 2026 00:00:00 GMT

小程序登录不是把前端传来的用户信息直接保存，而是由服务端向微信确认身份，再把微信身份转换成项目自己的登录态。本篇记录用户从临时 code 到业务 Token，以及登录后如何安全维护资料和地址。

1. 登录链路#

登录接口使用 @Anonymous 放行，但放行的只有入口，身份仍由后端验证：

1
wx.login code
2
  -> jscode2session
3
  -> openid / unionid
4
  -> 查询或创建 HyWxUser
5
  -> 构造 LoginUser
6
  -> TokenService.createToken

前端传来的 code 是一次性凭证，后端使用 AppID 和 Secret 调用微信 jscode2session。只有微信响应中的 openid 才能作为当前小程序内的稳定用户标识。

2. 首次登录的并发问题#

两个请求可能几乎同时完成 selectByOpenId，都认为用户不存在。只靠“先查再插”无法保证唯一性，所以数据库仍需要为 open_id 建唯一索引，并捕获 DuplicateKeyException：

1
try {
2
    insertHyWxUser(user);
3
} catch (DuplicateKeyException e) {
4
    user = selectHyWxUserByOpenId(openId);
5
}

应用层处理让第二个请求可以继续登录，数据库约束则保证不会真正产生两条用户记录，两层缺一不可。

3. 手机号授权与 access_token 缓存#

手机号授权凭证需要调用微信接口换取手机号，而这个接口又依赖全局 access_token。后端把 Token 缓存在内存中，并在微信给出的过期时间前 300 秒主动失效，减少临界点请求失败。

当微信返回 40001 或 42001 时，服务会清空缓存并重试一次。这里的重试只针对明确的 Token 失效，不对所有异常盲目重试，避免第三方服务故障时放大流量。

4. 接入项目自己的登录态#

微信用户没有后台角色和部门，但可以复用现有 Token 基础设施。后端构造最小 SysUser 与 LoginUser，用户名使用 wx_用户ID，权限集合为空，再交给 TokenService 生成 Token。

这样后续业务代码仍可统一调用：

1
Long userId = SecurityUtils.getUserId();
2
LoginUser loginUser = SecurityUtils.getLoginUser();

退出登录时删除服务端缓存中的 Token，而不是只让前端清空本地存储。

5. 资料更新使用字段白名单#

用户资料实体包含状态、删除标记、登录失败次数等后台字段。修改个人资料时不能把请求实体整体保存，而是新建更新对象，只复制允许修改的昵称：

1
HyWxUser update = new HyWxUser();
2
update.setUserId(SecurityUtils.getUserId());
3
update.setNickname(request.getNickname());
4
update.setUpdateTime(DateUtils.getNowDate());

头像接口也只返回 hasAvatar，真实存储路径保留在服务端。读取图片时先校验当前身份，再输出文件流。

6. 地址簿的资源归属#

地址的新增、修改、默认设置和删除都以安全上下文中的用户 ID 为准。即使请求体包含 wxUserId，后端也会覆盖它；修改前还要查询原记录并确认归属。

设置默认地址是一个整体动作：先查出当前用户所有有效地址，再把目标地址设为 1、其余设为 0，整个过程放在事务中。删除使用逻辑删除，同时取消默认标记，避免地址消失后仍残留默认状态。

7. code2Session 调用怎么实现#

后端调用微信登录服务时，需要把配置和临时 code 编码为查询参数：

1
private JsonNode codeToSession(String code) {
2
    String query = "appid=" + encode(miniProgramAppId)
3
            + "&secret=" + encode(miniProgramSecret)
4
            + "&js_code=" + encode(code)
5
            + "&grant_type=authorization_code";
6

7
    HttpRequest request = HttpRequest.newBuilder(
8
            URI.create(CODE_TO_SESSION_URL + "?" + query))
9
            .timeout(Duration.ofSeconds(8))
10
            .GET()
11
            .build();
12
    HttpResponse<String> response = httpClient.send(
13
            request, HttpResponse.BodyHandlers.ofString());
14
    return objectMapper.readTree(response.body());
15
}

展开收起

这里有四个值得注意的点：

所有参数都经过 URL 编码，不能直接拼接用户输入；
连接超时和单次请求超时分开配置，避免线程无限等待；
HTTP 2xx 只表示请求到达微信，不代表业务一定成功；
JSON 中还要检查 openid、errcode 和 errmsg。

如果 openid 为空，服务会把微信返回的业务错误转换为 ServiceException。Controller 不需要重复 try-catch，全局异常处理器会把它转为统一响应。

8. 首次登录为什么需要唯一索引#

首次登录的基本代码是：

1
HyWxUser user = selectHyWxUserByOpenId(openId);
2
if (user == null) {
3
    user = buildNewWxUser(openId, unionId);
4
    try {
5
        insertHyWxUser(user);
6
    } catch (DuplicateKeyException e) {
7
        user = selectHyWxUserByOpenId(openId);
8
    }
9
}

单线程下这段逻辑很直观，但并发情况下可能发生：

1
请求 A 查询：不存在
2
请求 B 查询：不存在
3
请求 A 插入：成功
4
请求 B 插入：触发唯一键冲突

捕获异常后重新查询，使请求 B 可以复用 A 已创建的用户。这里不能只依赖 synchronized，因为服务部署成多个实例后，每个实例都有自己的 JVM 锁。数据库的 open_id 唯一索引才是跨实例有效的最终约束。

9. Token 是怎样返回给小程序的#

微信身份确认后，项目把小程序用户转换成统一的 LoginUser：

1
private LoginUser buildLoginUser(WxLoginVo loginVo) {
2
    SysUser tokenUser = new SysUser();
3
    tokenUser.setUserName("wx_" + loginVo.getUserId());
4
    tokenUser.setNickName(loginVo.getNickname());
5
    tokenUser.setPhonenumber(loginVo.getMobile());
6
    tokenUser.setStatus("0");
7
    tokenUser.setDelFlag("0");
8
    return new LoginUser(
9
            loginVo.getUserId(), null,
10
            tokenUser, Collections.emptySet());
11
}

小程序用户没有后台部门与菜单权限，所以部门 ID 为空、权限集合为空，但仍能复用 Token 创建、刷新和注销逻辑。WxLoginResultVo 最终同时返回 Token 和经过裁剪的用户信息。

后续请求携带 Authorization，JWT 过滤器解析 Token，把 LoginUser 放入安全上下文。业务 Service 获取用户 ID 时读取的是服务端恢复的登录态，而不是请求体中的字段。

10. access_token 缓存代码拆解#

微信手机号接口需要全局 access_token。服务使用同步方法保证同一个进程内只有一个线程刷新：

1
private synchronized String getAccessToken() {
2
    long now = System.currentTimeMillis();
3
    if (StringUtils.isNotEmpty(cachedAccessToken)
4
            && cachedAccessTokenExpireTime > now) {
5
        return cachedAccessToken;
6
    }
7

8
    JsonNode result = requestAccessToken();
9
    String accessToken = result.path("access_token").asText();
10
    int expiresIn = result.path("expires_in").asInt(7200);
11
    long cacheSeconds = Math.max(
12
            60, expiresIn - 300);
13
    cachedAccessToken = accessToken;
14
    cachedAccessTokenExpireTime =
15
            now + cacheSeconds * 1000L;
16
    return cachedAccessToken;
17
}

展开收起

提前 300 秒过期是为了避开“本地判断仍有效，但请求到达微信时已经过期”的临界窗口。Math.max(60, ...) 防止第三方返回异常的短有效期后得到负数。

当手机号接口返回明确的 Token 失效码时，代码清空缓存并重试一次。只重试一次很重要：如果配置错误或微信持续异常，无限重试会让当前接口一直占用服务器线程。

11. 地址更新为什么重新构造对象#

用户提交的 HyUserAddress 中可能带有 wxUserId、删除标记和状态。Service 不把它原样交给 Mapper，而是创建白名单对象：

1
private HyUserAddress buildUserAddress(
2
        HyUserAddress source, Long wxUserId) {
3
    HyUserAddress target = new HyUserAddress();
4
    target.setWxUserId(wxUserId);
5
    target.setVesselName(source.getVesselName());
6
    target.setMmsi(source.getMmsi());
7
    target.setReceiverName(
8
            StringUtils.nvl(source.getReceiverName(), ""));
9
    target.setReceiverPhone(
10
            StringUtils.nvl(source.getReceiverPhone(), ""));
11
    target.setLongitude(source.getLongitude());
12
    target.setLatitude(source.getLatitude());
13
    return target;
14
}

wxUserId 使用安全上下文中的值，空姓名和电话被归一化为空字符串。未出现在复制列表中的后台字段不会被用户更新，这比依靠前端“不传那些字段”可靠得多。

12. 设置默认地址的事务过程#

默认地址需要满足“同一用户最多一条”。当前实现先确认目标地址归属，再查询用户全部有效地址并逐条更新：

1
@Transactional(rollbackFor = Exception.class)
2
public int setDefaultUserAddress(Long addressId) {
3
    Long wxUserId = SecurityUtils.getUserId();
4
    HyUserAddress target = selectById(addressId);
5
    checkAddressOwner(target, wxUserId);
6

7
    List<HyUserAddress> rows = selectByUserId(wxUserId);
8
    for (HyUserAddress row : rows) {
9
        HyUserAddress update = new HyUserAddress();
10
        update.setAddressId(row.getAddressId());
11
        update.setIsDefault(
12
                addressId.equals(row.getAddressId()) ? "1" : "0");
13
        mapper.updateHyUserAddress(update);
14
    }
15
    return 1;
16
}

展开收起

事务保证更新到一半发生异常时全部回滚。数据量增大后可以进一步改为两条条件 SQL：先清空当前用户默认值，再设置目标地址，减少循环产生的数据库往返。

13. 本篇小结#

登录功能真正解决的是“后端如何确认你是谁”，资料和地址功能解决的是“确认身份后你能改什么”。第三方身份校验、项目 Token、字段白名单与资源归属组合起来，才构成完整的用户边界。

后端开发日记①：多模块工程与业务接口分层

Sun, 28 Jun 2026 00:00:00 GMT

开始接触后端以后，第一件事不是立刻写接口，而是先弄清一次请求会经过哪些模块。这个项目从通用能力、权限框架到无人机配送业务都放在同一个 Maven 聚合工程里，如果没有先确定边界，很容易把业务代码写进入口模块，或者让 Controller 承担过多职责。

1. 工程模块怎么分#

父工程统一管理 Java 17、Spring Boot、MyBatis、PageHelper 等依赖版本，实际代码按职责拆分：

模块	职责
`uav-admin`	Web 服务启动入口与系统级 Controller
`uav-common`	返回结构、分页、异常、工具类等通用能力
`uav-framework`	Spring Security、Token、Redis 与系统配置
`uav-system`	用户、角色、菜单、字典等后台基础功能
`uav-quartz`	定时任务调度
`uav-generator`	数据表代码生成
`uav-manage`	订单、异常、飞行、用户、报表等配送业务

uav-admin 依赖其他模块并负责启动，但真正的配送逻辑集中在 uav-manage。这样既能复用后台框架，也不会让业务代码和系统管理代码互相缠绕。

2. 一次请求的调用链#

业务接口基本遵循四层结构：

1
HTTP 请求
2
  -> Controller：接收参数、鉴权、分页、组装响应
3
  -> Service：校验业务条件、控制事务、组织多表操作
4
  -> Mapper：声明数据访问方法
5
  -> Mapper XML：编写 SQL 与结果映射

例如用户查询异常反馈列表时，Controller 只负责开启分页并返回统一表格结构：

1
@GetMapping("/list")
2
public TableDataInfo list(HyExceptionTicket query) {
3
    startPage();
4
    List<HyExceptionTicket> rows = service.selectUserExceptionTicketList(query);
5
    return getDataTable(rows);
6
}

当前用户是谁、允许查询哪些数据，则由 Service 根据安全上下文补充，不能相信前端传来的用户 ID。

3. 两类接口边界#

同一张业务表会同时服务管理端和小程序，但两端权限完全不同。项目在 Controller 层直接区分：

controller/admin 面向后台人员，配合 @PreAuthorize 做菜单权限校验；
controller/user 面向当前微信用户，只允许访问自己的订单、地址、凭证和消息；
通用业务规则继续复用同一个 Service，避免两套状态逻辑逐渐不一致。

这种拆分比在一个接口里判断“来源是后台还是小程序”更清楚。接口路径本身就表达调用方，审查权限时也更容易发现遗漏。

4. 统一返回与分页#

普通接口使用 AjaxResult，列表接口使用 TableDataInfo。BaseController 已经封装了常见处理：

1
startPage();          // 从请求参数读取 pageNum、pageSize
2
getDataTable(list);   // 返回 rows、total、code、msg
3
toAjax(rows);         // 根据受影响行数返回成功或失败
4
success(data);        // 返回业务数据

分页必须在 Mapper 查询之前开启，因为 PageHelper 依赖当前线程中的分页参数。把 startPage() 放到查询之后，返回结构看起来仍然正确，实际却会一次读取全部数据。

5. DTO、实体和 VO 不混用#

项目里三类对象承担不同任务：

DTO 接收某个动作需要的参数，例如下单、审核、异常处置；
Entity 对应数据库记录，供 Mapper 读写；
VO 控制返回给前端的字段，例如只返回 hasImage，不暴露磁盘路径。

不是每个简单 CRUD 都必须建立三套对象，但涉及身份、文件路径或后台字段时，直接返回实体会扩大接口暴露面。后续的用户资料、配送凭证和报表接口都采用了这种隔离。

6. Spring 如何找到这些类#

项目启动类位于 com.ahebai 根包，@SpringBootApplication 默认从当前包向下扫描。只要各模块最终位于同一个运行时 classpath 中，下面这些类就会被注册到 Spring 容器：

1
@RestController
2
public class UserHyDeliveryOrderController {
3
}
4

5
@Service
6
public class HyDeliveryOrderServiceImpl
7
        implements IHyDeliveryOrderService {
8
}
9

10
@Configuration
11
public class ApplicationConfig {
12
}

这里需要区分“目录存在”和“Bean 已注册”。Java 文件放在 service 目录下不会自动变成 Service，真正触发组件扫描的是 @Service；配置类也必须通过 @Configuration 或显式导入进入容器。

Mapper 稍有不同。它是接口，没有可直接实例化的实现类，因此项目使用：

1
@MapperScan("com.ahebai.**.mapper")

MyBatis 会为扫描到的接口生成代理对象。当 Service 调用 hyDeliveryOrderMapper.select...() 时，运行的并不是手写 Java 实现，而是代理根据 namespace、方法名和参数找到 Mapper XML 中的 SQL。

7. 以查询接口为例看完整代码关系#

一个分页查询通常由 Controller、Service、Mapper 和 XML 四段组成。

Controller：

1
@GetMapping("/list")
2
public TableDataInfo list(HyDeliveryOrder query) {
3
    startPage();
4
    List<HyDeliveryOrder> rows =
5
            deliveryOrderService.selectUserDeliveryOrderList(query);
6
    return getDataTable(rows);
7
}

逐行来看：

@GetMapping 把 GET 请求映射到当前方法；
Spring MVC 把查询参数绑定到 query；
startPage() 读取 pageNum、pageSize 并设置 PageHelper 上下文；
Service 查询当前用户可见的订单；
getDataTable 使用实际列表和 PageHelper 统计结果生成 rows、total。

Service 不直接信任请求中的用户字段：

1
public List<HyDeliveryOrder> selectUserDeliveryOrderList(
2
        HyDeliveryOrder query) {
3
    HyDeliveryOrder safeQuery = query == null
4
            ? new HyDeliveryOrder() : query;
5
    safeQuery.setWxUserId(SecurityUtils.getUserId());
6
    safeQuery.setDelFlag("0");
7
    return deliveryOrderMapper.selectHyDeliveryOrderList(safeQuery);
8
}

这段代码同时补充了用户 ID 和有效数据标记。即使调用者传入另一个 wxUserId，最终也会被安全上下文中的值覆盖。

Mapper 接口只声明能力：

1
List<HyDeliveryOrder> selectHyDeliveryOrderList(
2
        HyDeliveryOrder query);

Mapper XML 再根据非空字段动态拼接 SQL。四层各自只处理自己理解的内容：Controller 理解 HTTP，Service 理解当前用户，Mapper 理解数据访问，XML 理解数据库字段。

8. 新增接口为什么更强调 Service#

查询失败通常不会改变数据，新增和状态流转则可能同时影响多张表。以创建订单为例：

1
@Transactional(rollbackFor = Exception.class)
2
public HyDeliveryOrder createUserDeliveryOrder(
3
        UserDeliveryOrderCreateDto createDto) {
4
    checkUserOrderRequired(createDto);
5
    HyDeliveryOrder order = buildUserDeliveryOrder(createDto);
6
    deliveryOrderMapper.insertHyDeliveryOrder(order);
7
    insertUserOrderProcessLog(
8
            order, "CREATE_ORDER", "用户下单",
9
            "用户提交订单，订单进入待支付状态");
10
    return order;
11
}

如果把“写订单”和“写过程日志”分别放在 Controller 中，第二步失败时第一步可能已经提交。Service 使用事务把它们定义为一个业务动作，异常抛出后由 Spring 事务代理统一回滚。

buildUserDeliveryOrder 的存在也很重要。它把 DTO 中允许使用的字段复制到实体，并由后端补充订单号、用户 ID、初始状态和创建时间。这样请求对象无法直接覆盖系统字段。

9. 模块依赖应该保持单向#

可以把当前项目的主要依赖简化为：

1
uav-admin
2
  ├─ uav-system
3
  ├─ uav-framework
4
  ├─ uav-quartz
5
  ├─ uav-generator
6
  └─ uav-manage
7
       ├─ uav-framework
8
       └─ uav-common

业务模块依赖通用模块是合理的，通用模块反过来依赖订单实体就会形成问题：以后任何项目想复用 uav-common，都被迫带上无人机配送业务。

代码层也遵循相同原则：

1
Controller -> Service -> Mapper
2
                    -> 第三方平台适配层
3
                    -> 其他领域 Service

当两个业务 Service 相互调用甚至形成循环依赖时，通常说明职责切分需要重新考虑。可以把共同动作抽成领域协作服务，或者通过事件和明确的编排 Service 组织，而不是让两个实现类互相注入。

10. 分层不是越多越好#

简单字典查询可能只需要 Controller、Service 和 Mapper，没有必要为每个字段再建立一层转换器。相反，订单、凭证和微信用户包含权限与敏感字段，就值得使用 DTO 和 VO。

判断是否拆层可以看三个问题：

这里是否跨越了 HTTP、业务、数据库或第三方平台边界？
这段逻辑是否需要被另一个入口复用？
这个对象是否包含调用方不应该写入或看到的字段？

只要其中一个答案为“是”，独立层或独立对象通常就有实际价值。分层的目标不是文件数量整齐，而是让变化被限制在正确的位置。

11. 本篇小结#

多模块并不是为了把目录变多，而是先划清稳定能力和业务能力的边界。Controller 保持薄、Service 承担业务、Mapper 专注数据访问，再配合统一响应和端侧隔离，后面的订单状态、异常处置与第三方平台接入才有清晰的落点。

Spring Boot 可观测性、测试体系与 OpenAPI 接口文档

Thu, 25 Jun 2026 00:00:00 GMT

一个接口在本地调用成功，并不代表它进入测试和生产环境后仍然容易维护。出现故障时，需要知道哪一个请求、经过哪些服务、在哪个 SQL 或外部调用上变慢；修改代码时，需要测试快速反馈行为是否被破坏；交给前端时，需要接口文档准确表达参数和错误。可观测性、测试和文档其实共同解决“系统行为能否被理解和验证”的问题。

1. 可观测性的三个互补信号#

通常把可观测性分为：

日志（Logs）：记录离散事件和上下文，适合回答某次请求发生了什么；
指标（Metrics）：记录可聚合数字，适合回答整体错误率、吞吐量和延迟是否异常；
追踪（Traces）：记录一次请求跨组件的调用路径，适合定位时间花在哪里。

只记录日志会难以观察趋势；只有指标又看不到具体失败原因；追踪没有业务字段时也很难关联订单。三者通过统一的请求标识、服务名和环境标签连接起来，才能形成完整视图。

2. 为每个请求生成追踪 ID#

单体应用也需要请求 ID。可以在过滤器中读取上游标识，没有则生成新的：

1
@Component
2
public class TraceIdFilter extends OncePerRequestFilter {
3

4
    private static final String TRACE_ID = "traceId";
5

6
    @Override
7
    protected void doFilterInternal(
8
            HttpServletRequest request,
9
            HttpServletResponse response,
10
            FilterChain chain) throws ServletException, IOException {
11

12
        String traceId = request.getHeader("X-Trace-Id");
13
        if (!StringUtils.hasText(traceId)) {
14
            traceId = UUID.randomUUID().toString().replace("-", "");
15
        }
16

17
        try {
18
            MDC.put(TRACE_ID, traceId);
19
            response.setHeader("X-Trace-Id", traceId);
20
            chain.doFilter(request, response);
21
        } finally {
22
            MDC.remove(TRACE_ID);
23
        }
24
    }
25
}

展开收起

日志格式加入 %X{traceId} 后，同一次请求的 Controller、Service 和 Mapper 日志就可以关联检索。响应头返回同一标识，前端反馈错误时可以直接提供它。

必须在 finally 清理 MDC。Web 容器线程会重复使用，不清理会让后续请求继承旧标识。异步线程也需要通过 TaskDecorator 显式传播并清理上下文。

3. 日志应该记录什么#

一条有用的业务日志通常包含事件名称、业务标识、结果、耗时和必要上下文：

1
long start = System.nanoTime();
2
try {
3
    deliveryService.dispatch(orderId);
4
    log.info("delivery_dispatch_success orderId={} costMs={}",
5
        orderId,
6
        elapsedMillis(start));
7
} catch (Exception e) {
8
    log.error("delivery_dispatch_failed orderId={} costMs={}",
9
        orderId,
10
        elapsedMillis(start),
11
        e);
12
    throw e;
13
}

错误日志要保留异常堆栈，不能只打印 e.getMessage()。但日志也不是越多越好：循环内逐条打印大对象会显著增加 I/O，完整请求体可能包含密码、Token、手机号或文件内容。应为敏感字段建立统一脱敏规则。

面向机器分析时，稳定字段比自然语言更有价值。无论使用 JSON 日志还是键值文本，都应保持 orderId、costMs、result 等字段命名一致。

4. 用统一入口观测请求耗时#

可以通过拦截器或过滤器记录 URI、状态码和耗时：

1
public class RequestTimingInterceptor
2
        implements HandlerInterceptor {
3

4
    private static final String START_TIME = "requestStartTime";
5

6
    @Override
7
    public boolean preHandle(
8
            HttpServletRequest request,
9
            HttpServletResponse response,
10
            Object handler) {
11
        request.setAttribute(START_TIME, System.nanoTime());
12
        return true;
13
    }
14

15
    @Override
16
    public void afterCompletion(
17
            HttpServletRequest request,
18
            HttpServletResponse response,
19
            Object handler,
20
            Exception ex) {
21
        long start = (long) request.getAttribute(START_TIME);
22
        long costMs = TimeUnit.NANOSECONDS.toMillis(
23
            System.nanoTime() - start);
24
        log.info("http_request method={} uri={} status={} costMs={}",
25
            request.getMethod(),
26
            request.getRequestURI(),
27
            response.getStatus(),
28
            costMs);
29
    }
30
}

展开收起

URI 指标不能直接使用包含订单号的真实路径，否则每个 ID 都会变成一个独立标签，造成高基数。应尽量记录路由模板，如 /orders/{id}，日志中再保留具体业务 ID。

5. Actuator 提供运行时观察入口#

引入 Actuator 后，可以按需开放健康、指标和信息端点：

1
management:
2
  endpoints:
3
    web:
4
      exposure:
5
        include: health,info,metrics,prometheus
6
  endpoint:
7
    health:
8
      show-details: when_authorized

健康端点适合部署平台判断实例状态，指标端点可以输出 JVM、HTTP、连接池和自定义业务指标。端点可能暴露环境、Bean 或线程信息，因此必须遵循最小暴露原则，并使用内网、网关或认证保护。

6. 自定义业务指标比只看 CPU 更有意义#

CPU 正常并不代表业务正常。可以记录订单调度成功与失败：

1
@Service
2
public class DeliveryMetrics {
3

4
    private final Counter dispatchSuccess;
5
    private final Counter dispatchFailure;
6

7
    public DeliveryMetrics(MeterRegistry registry) {
8
        this.dispatchSuccess = Counter.builder("delivery.dispatch.total")
9
            .tag("result", "success")
10
            .register(registry);
11
        this.dispatchFailure = Counter.builder("delivery.dispatch.total")
12
            .tag("result", "failure")
13
            .register(registry);
14
    }
15
}

展开收起

标签值必须是有限集合，例如 success、failure。不要把订单号、用户 ID 或异常消息作为指标标签，否则时间序列数量会不断增长。具体订单放日志和追踪，聚合维度放指标。

还可以观测订单处理延迟、第三方调用耗时、Redis 命中率、线程池队列长度和定时任务最后成功时间。告警应尽可能接近用户影响，例如连续五分钟订单调度失败率超过阈值，而不是仅仅监控进程是否存在。

7. 测试体系按反馈速度分层#

后端测试可以分为：

纯单元测试：不启动 Spring，验证业务分支，速度最快；
Controller 切片测试：只加载 MVC 和相关组件，验证协议、校验与响应；
Mapper/数据库集成测试：验证 SQL、事务和数据库方言；
完整应用测试：验证多个模块共同工作；
少量端到端测试：从真实入口覆盖核心用户路径。

层次越高，真实性越强，但启动更慢、故障定位更难。大部分业务分支应在快速测试中覆盖，把少量集成测试留给框架配置和基础设施边界。

8. 使用 Mockito 验证 Service 业务规则#

订单只能从待接单进入配送中，可以在不启动 Spring 的情况下测试：

1
@ExtendWith(MockitoExtension.class)
2
class DeliveryOrderServiceTest {
3

4
    @Mock
5
    private DeliveryOrderMapper orderMapper;
6

7
    @InjectMocks
8
    private DeliveryOrderServiceImpl orderService;
9

10
    @Test
11
    void shouldRejectDispatchWhenOrderIsCompleted() {
12
        DeliveryOrder order = new DeliveryOrder();
13
        order.setId(10L);
14
        order.setStatus(OrderStatus.COMPLETED.getCode());
15
        when(orderMapper.selectById(10L)).thenReturn(order);
16

17
        ServiceException exception = assertThrows(
18
            ServiceException.class,
19
            () -> orderService.dispatch(10L));
20

21
        assertEquals("当前状态不允许调度", exception.getMessage());
22
        verify(orderMapper, never()).updateStatus(anyLong(), anyInt(), anyInt());
23
    }
24
}

展开收起

这个测试同时验证输出和副作用：异常消息符合预期，而且 Mapper 没有执行更新。单元测试不应过度验证内部每一步调用，否则重构实现时会产生大量无意义修改；应围绕可观察业务行为断言。

9. 使用 MockMvc 验证接口协议#

Controller 测试关注路径、HTTP 方法、JSON、参数校验和权限响应：

1
@WebMvcTest(WxUserAddressController.class)
2
class WxUserAddressControllerTest {
3

4
    @Autowired
5
    private MockMvc mockMvc;
6

7
    @MockBean
8
    private WxUserAddressService addressService;
9

10
    @Test
11
    void shouldReturnValidationErrorWhenPhoneIsInvalid()
12
            throws Exception {
13
        String body = """
14
            {
15
              "receiverName": "张三",
16
              "receiverPhone": "123",
17
              "provinceId": 1,
18
              "detailAddress": "测试地址"
19
            }
20
            """;
21

22
        mockMvc.perform(post("/manage/user/address")
23
                .contentType(MediaType.APPLICATION_JSON)
24
                .content(body))
25
            .andExpect(status().isOk())
26
            .andExpect(jsonPath("$.code").value(500))
27
            .andExpect(jsonPath("$.msg").value("手机号格式不正确"));
28

29
        verifyNoInteractions(addressService);
30
    }
31
}

展开收起

如果项目统一用 HTTP 200 包装业务错误，测试应准确反映现有协议；从长期设计看，也可以逐步使用 400、401、403、404 和 409 等标准状态码，让网关和客户端更容易判断错误类型。

启用 Security 后，测试还应覆盖未登录、无权限和合法身份。不要为了让测试通过而整体关闭过滤器，否则最关键的安全链路没有被验证。

10. 数据库测试应使用真实方言#

MyBatis XML 可能使用 MySQL 的函数、分页和锁语法。H2 等内存数据库即使能运行，也不能完整代表生产数据库。可以使用 Testcontainers 启动临时 MySQL：

1
@Testcontainers
2
@SpringBootTest
3
class DeliveryOrderMapperIT {
4

5
    @Container
6
    static MySQLContainer<?> mysql =
7
        new MySQLContainer<>("mysql:8.4")
8
            .withDatabaseName("uav_test");
9

10
    @DynamicPropertySource
11
    static void datasourceProperties(
12
            DynamicPropertyRegistry registry) {
13
        registry.add("spring.datasource.url", mysql::getJdbcUrl);
14
        registry.add("spring.datasource.username", mysql::getUsername);
15
        registry.add("spring.datasource.password", mysql::getPassword);
16
    }
17
}

展开收起

测试结束后容器销毁，环境可重复。数据库迁移脚本也应作为测试启动过程的一部分，这样可以同时发现“代码期待的表结构”和“部署脚本实际创建的结构”不一致。

本段是可继续引入的工程化方案，并不表示所有项目已经配置 Testcontainers；采用前要结合现有构建环境和 CI 容器能力。

11. 测试数据应表达业务场景#

不要只创建一个所有字段均为默认值的实体。关键场景应明确命名：

pendingOrderOwnedByCurrentUser；
completedOrderCannotBeCancelled；
deletedAddressShouldNotBeReturned；
sameRequestShouldNotCreateDuplicateFeedback。

通过测试数据构造器集中填充不重要字段，让测试正文突出业务差异。每个测试独立准备数据，避免依赖执行顺序和共享可变状态。

12. OpenAPI 文档从 DTO 开始#

Springdoc 可以根据 Controller 和 DTO 生成 OpenAPI 文档。接口注解描述操作，模型注解描述字段：

1
@Tag(name = "微信用户地址")
2
@RestController
3
@RequestMapping("/manage/user/address")
4
public class WxUserAddressController {
5

6
    @Operation(summary = "新增收货地址")
7
    @PostMapping
8
    public AjaxResult create(
9
            @Valid @RequestBody AddressCreateRequest request) {
10
        return success(addressService.create(request));
11
    }
12
}

1
@Schema(description = "新增收货地址请求")
2
public class AddressCreateRequest {
3

4
    @Schema(description = "收件人姓名", example = "张三")
5
    @NotBlank
6
    private String receiverName;
7

8
    @Schema(description = "中国大陆手机号", example = "13800138000")
9
    @Pattern(regexp = "^1[3-9]\\d{9}$")
10
    private String receiverPhone;
11
}

文档不能替代参数校验。@Schema 告诉调用者应该传什么，@NotBlank、@Pattern 才会在运行时拒绝非法输入。将二者都写在 DTO 上，可以减少文档和实现漂移。

13. 统一响应也要被准确描述#

如果所有接口都返回 AjaxResult，文档只显示一个自由结构 Map，调用者无法知道 data 内容。可以为具体接口定义泛型响应或专用响应 DTO：

1
public class ApiResponse<T> {
2
    private Integer code;
3
    private String message;
4
    private T data;
5
}
6

7
public class AddressDetailResponse {
8
    private Long id;
9
    private String receiverName;
10
    private String receiverPhone;
11
    private String fullAddress;
12
}

即使现阶段仍使用统一包装，也应在 @ApiResponse 中描述常见错误：参数错误、未认证、无权限、资源不存在和状态冲突。错误码是一项对前端的稳定契约，不能随异常消息临时变化。

14. 文档访问也需要安全边界#

开发和测试环境可以开放 Swagger UI，生产环境应根据实际需求决定是否启用。若需要开放，应经过身份验证、网络限制或网关保护，避免直接暴露所有内部管理接口。

示例请求中不要填写真实手机号、密钥和 Token。第三方签名接口尤其要避免把 Secret 放进文档默认值。

15. 把日志、测试与文档串成反馈闭环#

一次功能迭代可以形成这样的链路：

DTO 和 OpenAPI 定义输入输出契约；
Controller 测试验证协议和校验；
Service 单元测试验证业务分支；
Mapper 集成测试验证 SQL 和事务；
上线后指标观察成功率和耗时；
异常通过 traceId 定位日志和具体业务记录；
线上问题沉淀为新的自动化测试，防止回归。

这比单独追求覆盖率数字更有价值。覆盖率只能说明代码被执行过，不能证明关键规则被正确断言。

16. 常见误区#

只在异常时打一句消息，没有堆栈和业务标识；
指标标签使用订单号，导致监控系统时间序列爆炸；
测试中大量使用 @SpringBootTest，反馈过慢且难定位；
Controller 测试关闭全部安全过滤器；
使用内存数据库验证生产 MySQL 特有 SQL；
文档直接暴露实体类，连内部状态和逻辑删除字段也成为输入；
Swagger 示例保存真实敏感信息；
只看代码覆盖率，不验证状态流转、越权和幂等。

17. 实践检查清单#

每个请求是否有可返回给调用者的追踪 ID；
日志是否包含业务标识、结果与耗时且完成脱敏；
是否观测 HTTP、数据库、Redis、线程池和第三方调用；
指标标签是否为有限集合；
核心业务规则是否有快速单元测试；
安全、校验和异常格式是否有 Controller 测试；
关键 SQL 是否使用真实数据库方言验证；
OpenAPI 是否使用专用 DTO 描述输入输出；
常见错误码是否有稳定说明；
线上故障修复后是否增加对应回归测试。

18. 小结#

可观测性让运行中的系统可以被解释，测试让修改后的系统可以被验证，OpenAPI 让系统边界可以被协作方理解。日志、指标、追踪、分层测试与 DTO 文档不是上线后的附属品，而是后端工程质量的一部分。把它们围绕同一业务契约组织起来，问题才能更快暴露、更快定位，也更不容易再次出现。

Spring 异步任务、线程池与优雅停机实践

Mon, 22 Jun 2026 00:00:00 GMT

把耗时逻辑放到异步线程，可以降低接口等待时间，但也会引入队列堆积、上下文丢失、异常无人处理、事务提前提交和服务关闭时任务丢失等问题。异步并不是简单地加一个 @Async，而是要把线程池当成一项有容量、有边界的运行资源。

1. 哪些任务适合异步#

适合异步的任务通常满足：

主流程不依赖它的即时返回值；
允许短时间延迟；
失败可以重试或补偿；
可以设计幂等；
能够单独监控成功和失败。

例如操作日志、非关键通知、报表快照和第三方状态同步可以考虑异步。库存扣减、订单状态确认等主流程关键步骤，如果接口已经向用户返回成功，就必须保证后续任务不会静默丢失。这类场景往往更适合可靠消息队列或 Outbox，而不是只放入进程内线程池。

2. `@Async` 仍然依赖 Spring 代理#

开启异步能力：

1
@EnableAsync
2
@Configuration
3
public class AsyncConfig {
4
}

异步方法放在 Spring Bean 中：

1
@Service
2
public class NotificationService {
3

4
    @Async("businessExecutor")
5
    public CompletableFuture<Void> sendOrderNotice(Long orderId) {
6
        // 调用消息平台
7
        return CompletableFuture.completedFuture(null);
8
    }
9
}

调用方拿到的是代理对象。代理拦截方法，把任务提交给指定线程池，当前请求线程无需等待任务执行完毕。与事务相同，同一个类内部使用 this.sendOrderNotice() 会绕过代理，方法仍在当前线程同步执行。可以将异步职责拆到独立 Bean，或通过事件进行解耦。

3. 明确配置业务线程池#

不应让所有任务共享一个参数不明确的默认执行器。一个可读的线程池配置如下：

1
@Bean("businessExecutor")
2
public ThreadPoolTaskExecutor businessExecutor() {
3
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
4
    executor.setCorePoolSize(8);
5
    executor.setMaxPoolSize(16);
6
    executor.setQueueCapacity(500);
7
    executor.setKeepAliveSeconds(60);
8
    executor.setThreadNamePrefix("business-async-");
9
    executor.setRejectedExecutionHandler(
10
        new ThreadPoolExecutor.CallerRunsPolicy());
11
    executor.setWaitForTasksToCompleteOnShutdown(true);
12
    executor.setAwaitTerminationSeconds(30);
13
    executor.initialize();
14
    return executor;
15
}

展开收起

线程名称能让日志和线程转储更容易定位来源。队列容量和拒绝策略明确后，高峰压力才不会无声地转化为无限内存增长。

4. 核心线程、最大线程和队列如何协作#

ThreadPoolExecutor 接收任务时大致遵循：

当前线程数小于核心线程数，创建核心线程；
核心线程已满，将任务放入队列；
队列已满且线程数小于最大线程数，创建额外线程；
队列和最大线程都已满，执行拒绝策略。

因此，如果队列设置得非常大，最大线程数可能长期不会生效。队列过小又会在短暂波动时频繁扩容或拒绝。参数应根据任务平均耗时、峰值到达速率、下游容量和可接受等待时间估算，并通过生产指标校准。

CPU 密集任务的线程数通常接近 CPU 核数；包含网络等待的 I/O 任务可以更多，但最终受数据库连接池、HTTP 连接池和第三方限流约束。线程开得比下游容量大，只会把等待搬到别处。

5. 拒绝策略决定过载时发生什么#

常见策略包括：

AbortPolicy：直接抛异常，失败明确；
CallerRunsPolicy：由提交任务的线程执行，形成反压；
DiscardPolicy：静默丢弃，不适合重要任务；
DiscardOldestPolicy：丢弃队列最旧任务，业务语义通常难以接受。

CallerRunsPolicy 会让接口线程自己执行任务，从而增加响应时间，但可以降低继续提交的速度。对于不能丢的任务，单靠拒绝策略仍不够，应持久化任务或交给消息队列，并提供重试与死信处理。

6. 不同任务使用不同线程池#

报表计算、日志写入和第三方 API 调用的耗时与失败模式不同。如果共享线程池，慢速第三方接口可能占满所有线程，连简单日志都无法执行。

可以按隔离边界配置：

1
@Async("reportExecutor")
2
public void buildSnapshot() {
3
}
4

5
@Async("thirdPartyExecutor")
6
public void syncDjiStatus() {
7
}

隔离后可以为第三方调用设置更短队列和更严格拒绝策略，为报表任务设置较少线程，防止它挤占在线请求资源。这种做法类似舱壁：一个依赖出现问题时，不让所有异步工作同时失效。

7. 请求上下文不会自动传播#

异步线程来自线程池，它不会天然继承请求线程中的 MDC、SecurityContext、语言环境和自定义 ThreadLocal。如果日志依赖追踪 ID，就要显式复制上下文：

1
public class MdcTaskDecorator implements TaskDecorator {
2

3
    @Override
4
    public Runnable decorate(Runnable runnable) {
5
        Map<String, String> contextMap = MDC.getCopyOfContextMap();
6
        return () -> {
7
            try {
8
                if (contextMap != null) {
9
                    MDC.setContextMap(contextMap);
10
                }
11
                runnable.run();
12
            } finally {
13
                MDC.clear();
14
            }
15
        };
16
    }
17
}

展开收起

1
executor.setTaskDecorator(new MdcTaskDecorator());

finally 中清理非常重要，因为线程会被复用。不清理会让下一项任务继承上一请求的追踪信息，产生错误日志关联甚至数据泄露。

业务身份最好作为明确参数传入异步方法，而不是在后台线程中继续读取当前请求用户。异步任务可能在请求结束很久后才执行，此时请求上下文本就不应再存在。

8. 异步异常必须有接收者#

返回 void 的异步方法抛出的异常无法返回给原请求线程，可以配置处理器：

1
@Configuration
2
public class AsyncExceptionConfig implements AsyncConfigurer {
3

4
    @Override
5
    public AsyncUncaughtExceptionHandler
6
            getAsyncUncaughtExceptionHandler() {
7
        return (throwable, method, params) ->
8
            log.error("异步任务执行失败, method={}, params={}",
9
                method.getName(), params, throwable);
10
    }
11
}

如果调用方需要知道结果，使用 CompletableFuture：

1
CompletableFuture<SyncResult> future =
2
    syncService.syncOrder(orderId);
3

4
future.whenComplete((result, error) -> {
5
    if (error != null) {
6
        log.error("订单同步失败, orderId={}", orderId, error);
7
    }
8
});

记录异常只是最低要求。关键任务还需要重试次数、下一次重试时间、最终失败状态和人工补偿入口。

9. 异步方法会开启新的事务边界#

请求线程中的事务上下文不会跨线程传播：

1
@Transactional
2
public void createOrder(CreateOrderRequest request) {
3
    DeliveryOrder order = saveOrder(request);
4
    notificationService.sendOrderNotice(order.getId());
5
}

异步任务可能在外层事务提交前就读取订单，导致查不到数据；也可能外层事务最终回滚，但通知已经发出。可以在事务提交后发布事件：

1
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
2
@Async("businessExecutor")
3
public void onOrderCreated(OrderCreatedEvent event) {
4
    notificationService.send(event.getOrderId());
5
}

这确保只有数据库提交成功后才提交异步工作，但进程在提交后、任务入队前崩溃仍可能丢失事件。要求可靠投递时，应使用事务消息或 Outbox 表。

10. 重试前必须先实现幂等#

网络超时不代表第三方没有成功处理。直接重试可能发送两次通知或创建两笔资源。可以为每个业务动作生成幂等键：

1
String idempotencyKey = "ORDER_NOTICE:" + orderId;
2
if (!taskRecordService.tryStart(idempotencyKey)) {
3
    return;
4
}
5

6
try {
7
    thirdPartyClient.sendNotice(orderId);
8
    taskRecordService.markSuccess(idempotencyKey);
9
} catch (Exception e) {
10
    taskRecordService.markFailed(idempotencyKey, e.getMessage());
11
    throw e;
12
}

幂等记录可以通过唯一索引防止重复创建。重试应区分可恢复错误和永久错误，例如网络超时可以指数退避重试，参数非法则应直接失败并告警。

11. 定时任务只负责调度，不承载大段业务#

订单超时扫描或报表快照任务应保持轻量：

1
@Component
2
public class DeliveryOrderTimeoutTask {
3

4
    private final DeliveryOrderTimeoutService timeoutService;
5

6
    @Scheduled(cron = "0 */1 * * * ?")
7
    public void execute() {
8
        timeoutService.processBatch();
9
    }
10
}

调度类决定何时触发，Service 决定查询哪些订单、如何抢占任务、怎样更新状态和记录结果。这样业务逻辑可以被普通单元测试覆盖，也能从手动补偿入口复用。

多个实例同时运行时，所有实例都会触发 @Scheduled。需要通过调度平台、分布式锁或数据库抢占控制重复执行，同时仍使用条件更新和幂等保证最终正确。

12. 长任务应分批并设置超时#

一次查询几十万条记录并放进线程池会同时占用内存、数据库连接和队列。更稳妥的方式是小批量拉取：

1
while (true) {
2
    List<Long> ids = orderMapper.selectPendingIds(200);
3
    if (ids.isEmpty()) {
4
        break;
5
    }
6
    processBatch(ids);
7
}

每批任务要有明确超时，第三方 HTTP 客户端同时设置连接、读取和整体调用超时。没有超时的线程可能永久占用池容量，让后续任务全部排队。

13. 优雅停机需要应用与平台配合#

线程池启用：

1
executor.setWaitForTasksToCompleteOnShutdown(true);
2
executor.setAwaitTerminationSeconds(30);

Spring Boot 服务同时启用：

1
server:
2
  shutdown: graceful
3

4
spring:
5
  lifecycle:
6
    timeout-per-shutdown-phase: 30s

发布时，负载均衡先停止向实例分配新流量，应用等待请求和异步任务完成，超过时间后才退出。对于执行数分钟的报表，不应无限延长停机时间，而应将任务进度持久化，使新实例可以继续。

进程内队列无法承诺跨重启保留任务。凡是“重启也不能丢”的工作，都应写入数据库或消息系统。

14. 线程池需要持续监控#

至少关注：

活跃线程数与最大线程数；
当前队列长度与队列容量；
已完成任务数；
拒绝任务数；
任务排队时间和执行时间；
异常数、超时数和重试数；
下游数据库连接池与 HTTP 连接池使用率。

只有执行耗时而没有排队耗时，会遗漏“任务本身很快，但在队列里等了十分钟”的问题。告警阈值也应与业务时效关联，而不是只看线程数。

15. 异步任务检查清单#

任务失败是否可以发现、重试和人工补偿；
是否具有业务幂等键；
是否误用同类内部调用导致 @Async 失效；
是否错误依赖请求线程的用户上下文；
线程池和下游连接池容量是否匹配；
队列满时的策略是否符合业务语义；
外层事务回滚时是否已经产生外部副作用；
应用重启时未完成任务是否会丢失；
是否为第三方请求配置所有必要超时；
多实例定时任务是否会重复执行。

16. 小结#

Spring 的 @Async 解决的是“把方法提交到另一个执行器”，不是可靠任务系统。线程池容量、拒绝策略、上下文清理、异常接收、事务提交时机、幂等和停机恢复共同决定异步链路是否可信。普通低风险工作可以使用进程内线程池；关键任务则应进一步使用持久化消息和可恢复状态。

Redis 缓存设计与分布式锁：从 Cache Aside 到并发控制

Fri, 19 Jun 2026 00:00:00 GMT

Redis 在 Spring Boot 项目中经常同时承担登录会话、系统配置、验证码、热点数据和并发协调等职责。它速度快，但“把数据库结果放进去”只是开始。键如何命名、何时失效、数据库更新失败怎么办、多个实例如何竞争同一任务，都会影响系统正确性。

1. 先判断数据是否适合缓存#

适合缓存的数据通常具有以下特点：

读取频率高，修改频率低；
查询或计算成本较高；
允许短时间内存在旧值；
可以定义明确的失效策略；
缓存丢失后仍能从权威数据源恢复。

系统配置就是典型例子。应用频繁读取配置键，但管理员很少修改。数据库是权威数据源，Redis 只是加速层。账户余额、库存扣减等强一致数据不能仅依赖普通缓存读写决定最终结果。

2. Cache Aside 的基本读路径#

项目中的系统配置服务可以采用旁路缓存模式：先查 Redis，未命中再查数据库并回填。

1
public String selectConfigByKey(String configKey) {
2
    String cacheKey = getCacheKey(configKey);
3
    String cachedValue = redisCache.getCacheObject(cacheKey);
4
    if (cachedValue != null) {
5
        return cachedValue;
6
    }
7

8
    SysConfig config = configMapper.selectConfigByKey(configKey);
9
    if (config == null) {
10
        return null;
11
    }
12

13
    redisCache.setCacheObject(cacheKey, config.getConfigValue());
14
    return config.getConfigValue();
15
}

展开收起

这段代码中，数据库仍然决定真实值。Redis 故障时，可以降级查询数据库；Redis 数据被清空时，也能逐步重建。不要让缓存成为唯一副本，否则缓存重启会变成数据事故。

3. 启动预热与按需加载如何选择#

若配置数量少且几乎每次请求都要使用，可以在服务启动后预加载：

1
@PostConstruct
2
public void init() {
3
    loadingConfigCache();
4
}

@PostConstruct 在依赖注入完成后执行，适合加载必要的小型字典或配置。预热的优点是第一笔请求不会承担数据库查询；缺点是数据过大或依赖暂时不可用时会拖慢甚至阻止启动。

普通业务列表更适合按需加载，并设置过期时间。是否预热需要根据数据规模、首请求时延和启动可用性决定，不应把所有表都在启动时读进 Redis。

4. 键命名要包含业务边界#

键名应当可读、可分组、不会与其他模块冲突：

1
sys:config:delivery.timeout.minutes
2
login:token:7e6c8b...
3
wx:user:profile:1024
4
delivery:order:detail:202608040001

建议结构为“系统或环境 + 模块 + 资源 + 标识”。多个环境共用 Redis 时，还要加入环境前缀：

1
prod:uav:sys:config:delivery.timeout.minutes
2
test:uav:sys:config:delivery.timeout.minutes

不要直接使用模糊短键，如 user:1 或 config:a。批量删除时也不要在生产代码中使用阻塞式 KEYS *，可以维护集合索引、按版本切换前缀，或使用渐进式扫描。

5. TTL 不只是节省空间#

过期时间同时决定旧数据最长存在多久。不同数据应使用不同 TTL：

登录会话与登录有效期一致，并在活跃时按策略续期；
验证码只保存几分钟，读取成功后立即删除；
热点详情可以缓存几分钟；
很少变化的系统配置可以长时间保存，但修改时主动清理；
分布式锁必须有较短的安全过期时间，避免持锁进程崩溃后永不释放。

永久缓存并非一定错误，但必须有主动更新、删除和重建机制。

6. 更新数据库后删除缓存#

Cache Aside 常用的写路径是先更新数据库，再删除缓存：

1
@Transactional
2
public void updateConfig(SysConfig config) {
3
    int rows = configMapper.updateConfig(config);
4
    if (rows != 1) {
5
        throw new ServiceException("配置更新失败");
6
    }
7
    redisCache.deleteObject(getCacheKey(config.getConfigKey()));
8
}

下一次读取会从数据库获得新值并回填。相比“同时更新数据库和缓存”，删除策略少维护一份值转换逻辑，也避免数据库成功而缓存写入旧结构。

不过，这里仍存在短暂竞态：请求 A 查询到旧数据库值，还未回填；请求 B 更新数据库并删除缓存；随后 A 把旧值写回。对于配置类数据，可以通过较短 TTL、更新后延迟二次删除或版本号减轻影响。强一致业务则应避免让缓存承担判断依据。

7. 事务与缓存操作不是同一个原子事务#

@Transactional 只能控制数据库事务，不能自动让 Redis 操作一起回滚。如果方法删除缓存后数据库事务最终回滚，缓存虽然丢失，但下次会重新读取旧数据库值，通常只是性能损失；若先写缓存后数据库回滚，则可能留下数据库中不存在的新值。

因此更常见的是数据库提交成功后再失效缓存。可以注册事务同步回调：

1
TransactionSynchronizationManager.registerSynchronization(
2
    new TransactionSynchronization() {
3
        @Override
4
        public void afterCommit() {
5
            redisCache.deleteObject(cacheKey);
6
        }
7
    });

对可靠性要求更高时，可以使用事务消息、Outbox 表或变更数据捕获，让缓存失效事件可重试、可观测。

8. 缓存穿透：查询不存在的数据#

攻击者反复查询随机 ID 时，Redis 永远未命中，所有请求都会落到数据库。这就是缓存穿透。常用方法包括：

在入口校验 ID 和业务参数格式；
对不存在结果缓存一个短时空值；
使用布隆过滤器判断标识是否可能存在；
对异常频率请求限流。

空值缓存示例：

1
if (data == null) {
2
    redisTemplate.opsForValue().set(
3
        cacheKey,
4
        NULL_MARKER,
5
        Duration.ofMinutes(2));
6
    return null;
7
}

空值 TTL 应比正常数据短，否则刚创建的新数据可能在一段时间内仍被旧空值遮挡。创建成功时也应主动删除对应空值键。

9. 缓存击穿：热点键同时失效#

当一个极热点键过期，大量请求同时发现未命中并访问数据库，会形成缓存击穿。可以使用互斥重建：只有一个线程加载数据库，其他线程短暂等待后重试。

另一种方案是逻辑过期：Redis 中保留数据和逻辑过期时间，过期后先返回旧值，再由一个线程异步刷新。这种方式保证响应速度，但业务必须允许短时间旧数据。

不能把锁等待设置得无限长。数据库异常时，等待线程会不断堆积。应配置较短超时、降级返回和失败告警。

10. 缓存雪崩：大量键同一时刻过期#

批量缓存若统一设置 30 分钟 TTL，可能在同一秒集中失效。可以加入随机抖动：

1
long baseSeconds = 1800;
2
long jitterSeconds = ThreadLocalRandom.current().nextLong(0, 300);
3
Duration ttl = Duration.ofSeconds(baseSeconds + jitterSeconds);

还可以将热点数据分批预热、限制数据库并发、准备降级值，并确保 Redis 本身具备高可用能力。雪崩治理不是只调整 TTL，而是要为缓存整体不可用时保护数据库。

11. 序列化格式决定可读性与兼容性#

Java 原生序列化体积大、跨语言差，也可能带来安全风险。JSON 更容易排查，但类型信息和日期格式需要明确。存对象时应考虑：

类字段新增或删除后旧缓存能否读取；
枚举值变化是否兼容；
是否把敏感字段写入缓存；
单个对象是否过大；
是否真的需要缓存整个实体。

许多场景只缓存字符串、数字或专用缓存 DTO，会比直接序列化数据库实体更稳定。

12. 分布式锁必须同时满足三件事#

多个应用实例竞争同一订单超时处理时，本地 synchronized 只能约束一个 JVM。Redis 锁的加锁需要原子地实现“不存在才写入并设置过期”：

1
String lockKey = "lock:delivery:timeout:" + orderId;
2
String lockValue = UUID.randomUUID().toString();
3

4
Boolean locked = redisTemplate.opsForValue().setIfAbsent(
5
    lockKey,
6
    lockValue,
7
    Duration.ofSeconds(30));
8

9
if (!Boolean.TRUE.equals(locked)) {
10
    return;
11
}

三个必要条件是：

SET NX 防止多个实例同时获得锁；
过期时间防止持锁进程崩溃造成死锁；
唯一 lockValue 防止线程删除其他实例后来获得的锁。

“先 setIfAbsent，再单独 expire”不是原子操作。进程可能在两条命令之间崩溃，留下永久锁。

13. 解锁必须比较令牌后再删除#

以下写法有并发错误：

1
// 不安全：可能删除别人的锁
2
redisTemplate.delete(lockKey);

假设线程 A 的锁过期，线程 B 获得同一键；随后 A 执行删除，就会删掉 B 的锁。比较和删除必须在 Redis 内原子完成，可使用 Lua：

1
if redis.call('get', KEYS[1]) == ARGV[1] then
2
    return redis.call('del', KEYS[1])
3
else
4
    return 0
5
end

1
DefaultRedisScript<Long> unlockScript =
2
    new DefaultRedisScript<>(UNLOCK_LUA, Long.class);
3

4
redisTemplate.execute(
5
    unlockScript,
6
    Collections.singletonList(lockKey),
7
    lockValue);

业务执行时间可能超过锁 TTL 时，需要续期机制，或使用 Redisson 等经过验证的锁实现。即使使用成熟库，也仍要理解等待时间、租约时间和故障语义。

14. 锁不能替代数据库幂等与状态条件#

分布式锁可能因网络分区、长暂停和过期时间估算错误失效。关键操作仍应通过唯一索引、幂等键或条件更新兜底：

1
UPDATE delivery_order
2
SET status = 'TIMEOUT'
3
WHERE id = #{orderId}
4
  AND status = 'PENDING'

即使两个实例都进入业务逻辑，也只有一个能把 PENDING 更新为 TIMEOUT。锁用于减少重复工作，数据库约束用于保证最终正确性。

15. 登录 Token 缓存与业务缓存要区分#

如果资源允许，也可以按用途拆分 Redis 实例，避免大量业务缓存淘汰登录会话，或慢命令影响认证链路。

16. 需要观测哪些指标#

命中率和未命中率；
Redis 请求耗时与错误率；
内存使用、淘汰数量和过期数量；
热点键、大键和慢命令；
数据库回源次数；
分布式锁获取成功率、等待时间和持有时间；
会话数量和异常失效数量。

命中率低不一定表示缓存无效，也可能是键粒度过细、TTL 过短或访问本身不重复。指标必须结合业务类型解释。

17. 小结#

Redis 缓存设计的核心是承认数据库仍是权威数据源，并为失效、并发和故障提前定义行为。Cache Aside、合理键名、分级 TTL、空值保护、随机过期和可观测指标解决读性能问题；唯一令牌、原子解锁和数据库条件更新共同解决分布式并发问题。缓存提升速度，但正确性仍需要完整链路保证。

Spring Boot 多环境配置与部署实践：从 YAML 到可执行服务

Tue, 16 Jun 2026 00:00:00 GMT

同一套 Spring Boot 代码通常要运行在本地、测试和生产环境。真正变化的不应该是 Java 代码，而是数据库地址、缓存节点、日志级别、第三方接口和运行参数。配置与部署设计得越清楚，发布时需要临时手改文件的风险就越低。

1. 配置的目标是让代码与环境解耦#

如果把数据库地址写进 Java 类，每次切换环境都要修改和重新编译：

1
// 不推荐
2
String jdbcUrl = "jdbc:mysql://127.0.0.1:3306/app";

更合理的方式是代码只声明需要什么配置，具体值由运行环境提供：

1
spring:
2
  datasource:
3
    url: ${DB_URL}
4
    username: ${DB_USERNAME}
5
    password: ${DB_PASSWORD}

${DB_URL} 表示从环境变量或启动参数中读取。配置文件可以进入版本管理，但真实密码不进入仓库。

2. 使用 Profile 拆分环境差异#

基础配置存放所有环境共同内容：

application.yml

1
spring:
2
  application:
3
    name: uav-delivery-manage
4
  profiles:
5
    active: ${SPRING_PROFILES_ACTIVE:dev}
6

7
server:
8
  shutdown: graceful

开发环境只覆盖差异：

application-dev.yml

1
logging:
2
  level:
3
    com.ahebai: debug
4

5
spring:
6
  datasource:
7
    url: jdbc:mysql://127.0.0.1:3306/uav_dev

生产环境则可以通过环境变量注入：

application-prod.yml

1
spring:
2
  datasource:
3
    url: ${DB_URL}
4
    username: ${DB_USERNAME}
5
    password: ${DB_PASSWORD}
6

7
logging:
8
  level:
9
    root: info

Profile 用于表达环境差异，不适合表达每个客户的业务分支。如果配置组合越来越多，应考虑配置中心或独立租户配置，而不是创建几十个 Profile 文件。

3. 理解配置覆盖顺序#

Spring Boot 会从多个来源读取配置。实践中常用的优先级可以这样理解：

命令行参数和系统属性用于临时覆盖；
环境变量用于部署平台注入；
当前 Profile 配置覆盖基础配置；
application.yml 提供默认值；
代码中的默认值作为最后兜底。

例如：

Terminal window

1
java -jar app.jar --server.port=9090

命令行的端口会覆盖 YAML。临时覆盖很方便，但生产环境要把最终参数纳入部署记录，否则服务器重启后很难解释“这个值为什么不同”。

4. 使用 `@ConfigurationProperties` 管理一组配置#

第三方无人机平台通常包含基础地址、应用标识、密钥和超时时间。相比在多个类中零散使用 @Value，配置对象更便于校验和复用：

1
dji:
2
  api:
3
    base-url: ${DJI_API_BASE_URL}
4
    app-key: ${DJI_APP_KEY}
5
    app-secret: ${DJI_APP_SECRET}
6
    connect-timeout: 3s
7
    read-timeout: 8s

1
@Validated
2
@ConfigurationProperties(prefix = "dji.api")
3
public class DjiApiProperties {
4

5
    @NotBlank
6
    private String baseUrl;
7

8
    @NotBlank
9
    private String appKey;
10

11
    @NotBlank
12
    private String appSecret;
13

14
    @NotNull
15
    private Duration connectTimeout = Duration.ofSeconds(3);
16

17
    @NotNull
18
    private Duration readTimeout = Duration.ofSeconds(8);
19
}

展开收起

@Validated 让应用在启动阶段发现缺失配置，而不是等第一笔业务请求到来才空指针。Duration 支持 3s、500ms 等可读格式，也避免不同代码对数字单位理解不一致。

5. 配置默认值要分安全与非安全两类#

端口、超时和线程数可以提供合理默认值：

1
server:
2
  port: ${SERVER_PORT:8080}

密码、签名密钥和生产数据库地址不应提供“看似可用”的默认值。否则环境变量遗漏后，应用可能连接到错误环境或使用弱密钥。对于关键配置，让启动失败比静默使用错误默认值更安全。

6. 敏感信息不能出现在代码和日志中#

需要保护的内容包括数据库密码、JWT 密钥、对象存储凭据、第三方平台 Secret 和用户 Token。基本原则包括：

不提交真实 Secret 到 Git；
使用部署平台 Secret、环境变量或专用密钥服务；
日志打印配置对象时对敏感字段脱敏；
定期轮换长期凭据；
测试环境和生产环境使用不同凭据；
发生泄露时先吊销，再清理历史记录。

仅仅删除最新提交中的密码并不代表安全，因为 Git 历史中仍可能存在。正确响应应当先将凭据视为已泄露并立即轮换。

7. 数据源配置要同时关注连接池#

项目可以将 Druid 等数据源配置放在独立文件中。除了 URL 和密码，还应关注连接池大小、连接验证和等待时间：

1
spring:
2
  datasource:
3
    druid:
4
      initial-size: 5
5
      min-idle: 5
6
      max-active: 30
7
      max-wait: 3000
8
      validation-query: SELECT 1

max-active 不是越大越好。若应用有 10 个实例，每个实例允许 100 个连接，数据库可能面对 1000 个连接。应从数据库容量、实例数、请求耗时和峰值并发共同计算，并监控连接等待和活跃连接数。

8. 日志配置也应区分环境#

本地开发可以打开包级 DEBUG，生产环境通常使用 INFO，并对慢请求和异常保留足够上下文：

1
logging:
2
  level:
3
    root: info
4
    com.ahebai: info
5
    org.springframework.security: warn
6
  file:
7
    name: ${LOG_PATH:./logs}/application.log

生产环境不建议长期输出完整 SQL 参数，尤其是用户手机号、证件信息和签名字段。调试问题时可以临时调整日志级别，但要有恢复机制，避免日志量突然增长占满磁盘。

9. 打包后的 Jar 如何启动#

Spring Boot 可执行 Jar 内含应用依赖和内嵌服务器，部署时无需额外安装 Tomcat：

Terminal window

1
java -jar app.jar --spring.profiles.active=prod

常见 JVM 参数包括：

Terminal window

1
java -Xms512m -Xmx1024m `
2
  -Duser.timezone=Asia/Shanghai `
3
  -jar app.jar `
4
  --spring.profiles.active=prod

堆内存应根据容器限制和非堆内存预留确定。不要把 -Xmx 设置为容器全部内存，否则线程栈、元空间、直接内存和本地库没有余量，进程仍可能被系统终止。

10. 使用容器固定运行环境#

一个简化的运行镜像可以写成：

1
FROM eclipse-temurin:17-jre
2

3
WORKDIR /app
4
COPY target/app.jar /app/app.jar
5

6
EXPOSE 8080
7
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

配置仍应从容器环境注入，而不是写入镜像。镜像标签最好包含版本号或提交标识，避免所有环境都使用不可追踪的 latest。运行用户应使用非 root 账号，基础镜像和依赖也要定期更新。

11. 健康检查不等于端口能连通#

应用端口打开，只说明进程已经监听，不代表数据库、Redis 和关键依赖可用。可通过 Actuator 暴露受控的健康端点：

1
management:
2
  endpoints:
3
    web:
4
      exposure:
5
        include: health,info,metrics
6
  endpoint:
7
    health:
8
      probes:
9
        enabled: true

存活检查回答“进程是否需要重启”，就绪检查回答“实例是否可以接收流量”。如果数据库短暂抖动，不一定应该立刻让存活检查失败并重启所有实例，否则可能放大故障。

管理端点不应无条件暴露到公网。需要通过网络隔离、认证和最小暴露列表保护。

12. 优雅停机保护正在处理的请求#

启用：

1
server:
2
  shutdown: graceful
3

4
spring:
5
  lifecycle:
6
    timeout-per-shutdown-phase: 30s

收到终止信号后，应用先停止接收新请求，再等待现有请求在限定时间内完成。部署平台也要给进程足够的终止宽限期。若平台五秒后强制杀死进程，而应用配置等待三十秒，优雅停机仍然无法发挥作用。

13. 滚动发布需要兼容过渡期#

发布过程中，新旧版本可能同时运行几分钟，因此数据库变更应兼容两代代码。更安全的顺序是：

先新增可空字段或新表，不立即删除旧结构；
发布能同时兼容新旧结构的代码；
完成数据回填和观测；
所有实例升级后，再停止写旧字段；
后续版本中清理旧字段。

直接重命名字段或修改枚举含义，容易让旧实例在滚动期间报错。配置变更也要考虑回滚：新版本新增的必填配置，在回滚到旧版本时是否会造成副作用。

14. 部署失败时如何定位#

可以按启动链路逐层检查：

进程是否启动，退出码是什么；
Java 版本是否符合项目要求；
当前激活的 Profile 是否正确；
必填环境变量是否注入；
数据库和 Redis 网络是否可达；
配置绑定或 Bean 创建在哪一步失败；
端口是否冲突；
健康检查路径和权限是否正确；
实例是否因内存限制被系统终止。

保留启动日志和最终生效配置的非敏感摘要，通常比反复重启更有帮助。

15. 发布前检查清单#

配置文件中是否不存在真实密码和 Token；
环境变量名称是否与 @ConfigurationProperties 一致；
数据库迁移是否向前、向后兼容；
日志目录、轮转和磁盘告警是否就绪；
健康端点是否受保护且能区分存活与就绪；
JVM 内存是否为线程栈和直接内存留出空间；
优雅停机时间是否与平台宽限期匹配；
镜像、Jar、配置和数据库版本是否可追踪；
回滚步骤是否经过书面确认。

16. 小结#

多环境配置的核心不是多写几个 YAML，而是让代码、普通配置和敏感凭据各自处在正确位置。部署也不只是执行 java -jar，还包括资源限制、健康检查、日志、优雅停机、数据库兼容和回滚路径。把这些内容纳入开发阶段，服务才能从“本地能运行”走向“环境中可维护”。

MyBatis 动态 SQL、分页与性能优化实践

Sat, 13 Jun 2026 00:00:00 GMT

MyBatis 的优势是 SQL 可见、可控，也因此把更多责任交给开发者：条件组合是否正确、参数是否安全、分页是否稳定、索引是否生效，都需要在代码和数据库之间共同判断。本文从一个地址关键词查询开始，逐步梳理 Mapper 到 SQL 执行的完整过程。

1. Mapper 接口为什么不需要实现类#

项目通过 @MapperScan("com.ahebai.**.mapper") 扫描 Mapper 接口。启动时，MyBatis 为接口创建代理对象并注册到 Spring 容器：

1
public interface WxUserAddressMapper {
2

3
    List<WxUserAddress> searchAddress(
4
        @Param("wxUserId") Long wxUserId,
5
        @Param("keyword") String keyword);
6
}

XML 中的 namespace 必须等于接口全限定名，语句 id 必须等于方法名：

1
<mapper namespace="com.ahebai.manage.mapper.WxUserAddressMapper">
2
    <select id="searchAddress"
3
            resultMap="WxUserAddressResult">
4
        SELECT id, wx_user_id, receiver_name,
5
               receiver_phone, detail_address
6
        FROM wx_user_address
7
        WHERE wx_user_id = #{wxUserId}
8
          AND deleted = 0
9
    </select>
10
</mapper>

调用接口方法时，代理根据“接口名 + 方法名”定位 SQL，绑定参数并把结果转换为对象。因此接口重命名、XML 命名空间和语句 ID 必须同步修改。

2. `@Param` 让参数名保持稳定#

当 Mapper 方法有多个参数时，应显式使用 @Param：

1
List<DeliveryOrder> selectPage(
2
    @Param("status") Integer status,
3
    @Param("wxUserId") Long wxUserId,
4
    @Param("keyword") String keyword);

XML 可以稳定使用 #{status}、#{wxUserId} 和 #{keyword}。如果依赖编译器是否保留参数名，不同构建配置下可能出现 Parameter 'xxx' not found。明确命名也让 SQL 的语义更容易阅读。

3. `resultMap` 负责数据库列到对象字段的映射#

字段命名不一致或需要关联对象时，可以使用 resultMap：

1
<resultMap id="WxUserAddressResult"
2
           type="WxUserAddress">
3
    <id property="id" column="id"/>
4
    <result property="wxUserId" column="wx_user_id"/>
5
    <result property="receiverName" column="receiver_name"/>
6
    <result property="receiverPhone" column="receiver_phone"/>
7
    <result property="detailAddress" column="detail_address"/>
8
</resultMap>

<id> 不只是普通字段标记，MyBatis 在处理关联结果时会借助它识别相同主对象。查询字段应显式列出，避免使用 SELECT * 导致无关大字段被加载，也避免表结构新增列后不知不觉改变查询成本。

4. 使用 `<where>` 和 `<if>` 组合动态条件#

列表查询常见多个可选筛选条件：

1
<select id="selectOrderList"
2
        resultMap="DeliveryOrderResult">
3
    SELECT id, order_no, wx_user_id,
4
           status, create_time
5
    FROM delivery_order
6
    <where>
7
        deleted = 0
8
        <if test="wxUserId != null">
9
            AND wx_user_id = #{wxUserId}
10
        </if>
11
        <if test="status != null">
12
            AND status = #{status}
13
        </if>
14
        <if test="keyword != null and keyword != ''">
15
            AND (
16
                order_no LIKE CONCAT('%', #{keyword}, '%')
17
                OR receiver_name LIKE CONCAT('%', #{keyword}, '%')
18
                OR receiver_phone LIKE CONCAT('%', #{keyword}, '%')
19
            )
20
        </if>
21
    </where>
22
    ORDER BY create_time DESC, id DESC
23
</select>

展开收起

<where> 会在存在条件时自动添加 WHERE，并清理开头多余的 AND 或 OR。关键词的三个 OR 必须放在括号内，否则 SQL 运算优先级可能让 deleted = 0 和用户条件只约束第一个分支，造成已删除数据或其他用户数据被查出。

5. `#{}` 与 `${}` 的安全差异#

#{keyword} 通过预编译参数绑定，数据库把输入当作值；${keyword} 是字符串直接替换，可能形成 SQL 注入：

1
<!-- 正确：值参数 -->
2
WHERE order_no = #{orderNo}
3

4
<!-- 危险：客户端输入直接拼接 -->
5
ORDER BY ${sortField} ${sortDirection}

排序字段不能用 #{} 代替列名。如果确实需要动态排序，应在 Java 中把用户输入映射到固定枚举，再在 XML 中白名单选择：

1
<choose>
2
    <when test="sortField == 'status'">
3
        ORDER BY status
4
    </when>
5
    <when test="sortField == 'orderNo'">
6
        ORDER BY order_no
7
    </when>
8
    <otherwise>
9
        ORDER BY create_time
10
    </otherwise>
11
</choose>

方向也只允许 ASC 或 DESC，不要把任意字符串放进 SQL。

6. 使用 `<foreach>` 处理批量参数#

批量查询和批量更新可以避免循环执行多次 SQL：

1
List<DeliveryOrder> selectByIds(
2
    @Param("ids") List<Long> ids,
3
    @Param("wxUserId") Long wxUserId);

1
SELECT id, order_no, status
2
FROM delivery_order
3
WHERE wx_user_id = #{wxUserId}
4
  AND deleted = 0
5
  AND id IN
6
<foreach collection="ids"
7
         item="id"
8
         open="(" separator="," close=")">
9
    #{id}
10
</foreach>

Service 层要先判断集合非空，并限制单次批量数量。几万个 ID 会产生超长 SQL、增加解析成本，也可能超过数据库或驱动限制。通常应按几百或一千条分批处理，并在事务和内存之间取得平衡。

7. PageHelper 的调用顺序决定分页是否生效#

PageHelper 通过线程上下文和 MyBatis 拦截器改写紧随其后的查询：

1
public TableDataInfo list(OrderQuery query) {
2
    startPage();
3
    List<DeliveryOrder> list =
4
        orderService.selectOrderList(query);
5
    return getDataTable(list);
6
}

startPage() 必须位于目标查询之前。中间如果先执行了其他查询，分页可能作用到错误 SQL。分页参数也要设置最大值，避免客户端请求一页十万条数据。

分页查询通常会额外执行一条 COUNT。复杂关联和分组查询的计数可能很慢，可以针对列表场景编写更简单的计数 SQL，或在不需要总条数的滚动加载中使用“是否还有下一页”模式。

8. 稳定排序防止翻页重复和遗漏#

只按 create_time DESC 排序并不稳定，因为多条记录可能拥有同一时间。数据库可以在并列记录间使用任意顺序，第二页可能重复第一页的数据。加入唯一主键作为第二排序条件：

1
ORDER BY create_time DESC, id DESC

数据量很大且页码很深时，LIMIT 100000, 20 仍需扫描并丢弃大量记录。可以改为游标分页：

1
SELECT id, order_no, create_time
2
FROM delivery_order
3
WHERE deleted = 0
4
  AND (
5
      create_time < #{lastCreateTime}
6
      OR (create_time = #{lastCreateTime} AND id < #{lastId})
7
  )
8
ORDER BY create_time DESC, id DESC
9
LIMIT 20

客户端携带上一页最后一条记录的时间和 ID，数据库可以从索引位置继续扫描，适合时间线和无限滚动列表。

9. 识别并消除 N+1 查询#

如果先查询 100 个订单，再循环查询每个订单的用户信息，就会执行 101 条 SQL：

1
List<DeliveryOrder> orders = orderMapper.selectList(query);
2
for (DeliveryOrder order : orders) {
3
    order.setUser(userMapper.selectById(order.getWxUserId()));
4
}

可以根据数据关系选择联表查询，或先收集全部用户 ID 再批量查询并组装：

1
Set<Long> userIds = orders.stream()
2
    .map(DeliveryOrder::getWxUserId)
3
    .collect(Collectors.toSet());
4

5
Map<Long, WxUser> userMap = userMapper.selectByIds(userIds)
6
    .stream()
7
    .collect(Collectors.toMap(WxUser::getId, Function.identity()));
8

9
orders.forEach(order ->
10
    order.setUser(userMap.get(order.getWxUserId())));

联表适合数据量可控、关系简单的查询；批量组装更适合需要复用缓存或避免复杂笛卡尔积的场景。

10. 聚合统计尽量让数据库一次完成#

分别查询待接单、配送中、已完成数量会执行多条扫描。可以使用条件聚合：

1
SELECT
2
    SUM(CASE WHEN status = 0 THEN 1 ELSE 0 END) AS pending_count,
3
    SUM(CASE WHEN status = 1 THEN 1 ELSE 0 END) AS delivering_count,
4
    SUM(CASE WHEN status = 2 THEN 1 ELSE 0 END) AS completed_count
5
FROM delivery_order
6
WHERE deleted = 0
7
  AND create_time >= #{startTime}

一次扫描返回多个指标，既减少网络往返，也让统计口径共享相同条件。若统计跨度很大且访问频繁，则应进一步考虑汇总表或定时快照，而不是每次扫描明细表。

11. 索引要围绕查询条件和排序设计#

索引不是越多越好。对于以下查询：

1
WHERE wx_user_id = ?
2
  AND deleted = 0
3
ORDER BY create_time DESC, id DESC

可以评估联合索引 (wx_user_id, deleted, create_time, id)。等值条件通常放在前面，排序字段随后。最终设计仍要结合字段区分度、写入频率和其他查询，不应只凭一条 SQL 决定。

LIKE '%关键词%' 因为开头有通配符，普通 B+Tree 索引通常无法完成前缀定位。数据量小时可以接受；数据量大时应考虑前缀搜索、倒排索引或专用搜索服务，而不是不断追加普通索引。

12. 用执行计划验证推测#

性能优化不能只看 SQL 长短，应使用 EXPLAIN 观察：

实际使用了哪个索引；
预计扫描多少行；
是否出现全表扫描；
是否发生额外排序或临时表；
联表顺序是否合理。

优化后还要用接近生产分布的数据重新测量。开发库只有几十条记录时，数据库选择全表扫描可能反而更快，不能代表生产环境表现。

13. 更新语句也要表达业务前置条件#

订单状态更新不要先查再无条件写入：

1
UPDATE delivery_order
2
SET status = #{targetStatus},
3
    update_time = NOW()
4
WHERE id = #{orderId}
5
  AND status = #{expectedStatus}
6
  AND deleted = 0

如果影响行数为零，说明订单不存在或已经被其他请求修改。条件更新把状态机前置条件交给数据库原子判断，可以减少并发覆盖问题。它与事务并不冲突：事务负责一组操作的整体一致性，条件更新负责单条语句的并发竞争。

14. Mapper 测试应验证 SQL 语义#

Mapper 测试重点不是“方法能调用”，而是动态条件是否组合正确：

keyword 为空时是否省略模糊条件；
多个 OR 是否被括号正确包裹；
逻辑删除和用户隔离条件是否始终存在；
空集合是否生成非法 IN ()；
同时间数据的分页顺序是否稳定；
条件更新在状态不匹配时是否返回零行。

对于数据库方言、索引和锁行为，使用真实 MySQL 的集成测试比内存数据库更可信。

15. 小结#

MyBatis 让 SQL 成为业务代码的一部分。写好 Mapper 不仅是把语句放进 XML，还要同时考虑安全参数、动态条件优先级、分页稳定性、查询次数、索引路径和并发前置条件。保持 SQL 可读、用执行计划验证、用集成测试保护关键语义，才能真正发挥“可控”的优势。

Spring Security 请求链与参数校验：从 JWT 到资源归属校验

Wed, 10 Jun 2026 00:00:00 GMT

后端安全并不只是“登录成功后发一个 Token”。一次请求从进入应用到执行 Controller，至少会经历跨域处理、Token 提取、身份解析、权限判断、参数校验、业务规则校验和资源归属校验。任何一层缺失，都可能让一个表面正常的接口留下越权入口。

1. 先区分认证、授权与资源归属#

这三个概念经常被混在一起：

认证（Authentication）：回答“当前请求是谁发出的”；
授权（Authorization）：回答“这个角色能不能调用该功能”；
资源归属（Ownership）：回答“这个用户能不能操作这一条具体数据”。

例如，普通微信用户已经登录，说明认证通过；他可以修改收货地址，说明功能授权通过；但他只能修改自己的地址，最后还必须校验地址记录中的 wxUserId 是否等于当前用户。这一步不能只依赖前端隐藏按钮，也不能只依赖路径权限。

2. 无状态请求的安全过滤链#

项目采用前后端分离模式，服务端不保存传统 Session，会话状态由 JWT 和 Redis 共同维护。核心配置可以概括为：

1
@Bean
2
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
3
    return http
4
        .csrf(AbstractHttpConfigurer::disable)
5
        .sessionManagement(session -> session
6
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
7
        .authorizeHttpRequests(auth -> auth
8
            .requestMatchers("/login", "/register", "/captchaImage").permitAll()
9
            .requestMatchers("/manage/user/wx-user/login").permitAll()
10
            .requestMatchers(HttpMethod.GET, "/profile/**").denyAll()
11
            .anyRequest().authenticated())
12
        .addFilterBefore(corsFilter, JwtAuthenticationTokenFilter.class)
13
        .addFilterBefore(jwtAuthenticationTokenFilter,
14
            UsernamePasswordAuthenticationFilter.class)
15
        .build();
16
}

展开收起

STATELESS 表示 Spring Security 不创建和读取服务器 Session。permitAll() 只表示这些路径无需登录，并不表示其中的业务参数可以不校验。anyRequest().authenticated() 则建立兜底规则：没有被明确放行的接口默认需要身份。

过滤器顺序也有实际意义。跨域过滤器需要尽早处理浏览器的预检请求；JWT 过滤器必须在用户名密码认证过滤器之前写入当前身份，后续授权逻辑才能读取 SecurityContext。

3. JWT 过滤器到底做了什么#

JWT 过滤器的职责应当保持单一：读取请求头、解析登录标识、恢复用户身份并交给后续过滤器。典型结构如下：

1
@Component
2
public class JwtAuthenticationTokenFilter
3
        extends OncePerRequestFilter {
4

5
    private final TokenService tokenService;
6

7
    @Override
8
    protected void doFilterInternal(
9
            HttpServletRequest request,
10
            HttpServletResponse response,
11
            FilterChain chain) throws ServletException, IOException {
12

13
        LoginUser loginUser = tokenService.getLoginUser(request);
14

15
        if (loginUser != null
16
                && SecurityContextHolder.getContext().getAuthentication() == null) {
17
            tokenService.verifyToken(loginUser);
18

19
            UsernamePasswordAuthenticationToken authentication =
20
                new UsernamePasswordAuthenticationToken(
21
                    loginUser,
22
                    null,
23
                    loginUser.getAuthorities());
24

25
            authentication.setDetails(
26
                new WebAuthenticationDetailsSource().buildDetails(request));
27
            SecurityContextHolder.getContext()
28
                .setAuthentication(authentication);
29
        }
30

31
        chain.doFilter(request, response);
32
    }
33
}

展开收起

OncePerRequestFilter 保证同一请求分派过程中只执行一次。过滤器没有直接调用 Controller，而是通过 chain.doFilter 把请求交给下一环节。身份对象写入 SecurityContextHolder 后，@PreAuthorize、权限表达式以及业务层获取当前用户的方法才能使用它。

JWT 中不宜保存随时变化的完整用户信息。更稳妥的做法是只携带随机登录标识，详细登录状态放在 Redis 中。这样禁用账号、退出登录或刷新权限时，可以主动删除或更新 Redis 会话，而不必等待旧 JWT 自然过期。

4. URL 授权与方法授权要相互补充#

URL 规则适合声明整体边界，方法注解适合表达具体业务权限：

1
@EnableMethodSecurity(
2
    prePostEnabled = true,
3
    securedEnabled = true)
4
@Configuration
5
public class SecurityConfig {
6
}

1
@PreAuthorize("@ss.hasPermi('delivery:order:edit')")
2
@PutMapping("/{orderId}/status")
3
public AjaxResult updateStatus(
4
        @PathVariable Long orderId,
5
        @Valid @RequestBody OrderStatusRequest request) {
6
    orderService.updateStatus(orderId, request);
7
    return success();
8
}

方法权限应写在真正的业务入口上，避免只保护菜单而漏掉接口。新增接口时也要检查是否沿用了对应权限；否则前端没有入口，攻击者仍可直接构造 HTTP 请求。

5. 资源归属校验必须下沉到业务层#

假设修改地址接口接收地址 ID。如果只执行 updateById，登录用户把路径中的 ID 换成其他人的 ID 就可能越权：

1
@Transactional
2
public void updateAddress(Long addressId, AddressUpdateRequest request) {
3
    Long currentUserId = securityUserService.getCurrentWxUserId();
4

5
    WxUserAddress address = addressMapper.selectById(addressId);
6
    if (address == null || Boolean.TRUE.equals(address.getDeleted())) {
7
        throw new ServiceException("地址不存在");
8
    }
9
    if (!Objects.equals(address.getWxUserId(), currentUserId)) {
10
        throw new ServiceException("无权操作该地址");
11
    }
12

13
    address.setReceiverName(request.getReceiverName());
14
    address.setReceiverPhone(request.getReceiverPhone());
15
    address.setDetailAddress(request.getDetailAddress());
16
    addressMapper.updateById(address);
17
}

展开收起

更紧凑的做法是让 SQL 同时限定主键和当前用户：

1
UPDATE wx_user_address
2
SET receiver_name = #{receiverName},
3
    receiver_phone = #{receiverPhone},
4
    detail_address = #{detailAddress}
5
WHERE id = #{addressId}
6
  AND wx_user_id = #{currentUserId}
7
  AND deleted = 0

然后检查影响行数是否为 1。这种“带条件更新”不仅能防止越权，也能减少查询后再更新之间的竞态窗口。

6. DTO 参数校验是第一道业务边界#

Controller 不应该接收一个包含所有数据库字段的实体类。实体中可能有 status、createBy、deleted 等不允许客户端修改的字段。为具体接口建立 DTO，可以同时限制字段集合和校验规则：

1
public class AddressCreateRequest {
2

3
    @NotBlank(message = "收件人不能为空")
4
    @Size(max = 30, message = "收件人不能超过30个字符")
5
    private String receiverName;
6

7
    @NotBlank(message = "手机号不能为空")
8
    @Pattern(
9
        regexp = "^1[3-9]\\d{9}$",
10
        message = "手机号格式不正确")
11
    private String receiverPhone;
12

13
    @NotNull(message = "省级行政区不能为空")
14
    private Long provinceId;
15

16
    @NotBlank(message = "详细地址不能为空")
17
    @Size(max = 200, message = "详细地址不能超过200个字符")
18
    private String detailAddress;
19
}

展开收起

1
@PostMapping
2
public AjaxResult create(
3
        @Valid @RequestBody AddressCreateRequest request) {
4
    return success(addressService.create(request));
5
}

@Valid 触发对象字段校验。对于查询参数、路径变量等方法参数，还需要在类上添加 @Validated：

1
@Validated
2
@RestController
3
public class AddressController {
4

5
    @GetMapping("/{id}")
6
    public AjaxResult detail(
7
            @PathVariable @Positive Long id) {
8
        return success(addressService.detail(id));
9
    }
10
}

7. 字段校验不能替代业务规则#

注解擅长判断非空、长度、格式和数值范围，却无法判断“这个行政区是否存在”“用户是否已有十个地址”“订单当前是否允许取消”。这些规则仍应由 Service 负责：

1
public Long create(AddressCreateRequest request) {
2
    Long userId = securityUserService.getCurrentWxUserId();
3

4
    if (!regionService.isValidPath(
5
            request.getProvinceId(),
6
            request.getCityId(),
7
            request.getDistrictId())) {
8
        throw new ServiceException("行政区划层级不匹配");
9
    }
10

11
    int count = addressMapper.countActiveByUserId(userId);
12
    if (count >= 10) {
13
        throw new ServiceException("最多只能保存10个收货地址");
14
    }
15

16
    return addressMapper.insert(toEntity(userId, request));
17
}

展开收起

一个实用的分工是：Controller 处理协议格式，Service 处理业务规则，数据库约束处理最终一致性。三者不是互相替代，而是逐层缩小非法数据进入系统的可能性。

8. 跨字段规则可以使用类级校验器#

当“预约开始时间必须早于结束时间”涉及两个字段时，可以建立自定义注解：

1
@ValidTimeRange
2
public class AppointmentRequest {
3
    @NotNull
4
    private LocalDateTime startTime;
5

6
    @NotNull
7
    private LocalDateTime endTime;
8
}

1
public class TimeRangeValidator
2
        implements ConstraintValidator<ValidTimeRange, AppointmentRequest> {
3

4
    @Override
5
    public boolean isValid(
6
            AppointmentRequest value,
7
            ConstraintValidatorContext context) {
8
        if (value == null
9
                || value.getStartTime() == null
10
                || value.getEndTime() == null) {
11
            return true;
12
        }
13
        return value.getStartTime().isBefore(value.getEndTime());
14
    }
15
}

展开收起

空值交给 @NotNull 处理，类级校验器只关心字段间关系，可以避免同一错误被重复报告。

9. 统一异常返回让前端正确处理错误#

参数校验失败通常抛出 MethodArgumentNotValidException，表单绑定可能抛出 BindException，业务拒绝则使用统一的 ServiceException。全局异常处理器把它们转换为稳定的响应格式：

1
@RestControllerAdvice
2
public class GlobalExceptionHandler {
3

4
    @ExceptionHandler(MethodArgumentNotValidException.class)
5
    public AjaxResult handleValidException(
6
            MethodArgumentNotValidException e) {
7
        String message = e.getBindingResult()
8
            .getFieldErrors()
9
            .stream()
10
            .map(FieldError::getDefaultMessage)
11
            .findFirst()
12
            .orElse("参数校验失败");
13
        return AjaxResult.error(message);
14
    }
15

16
    @ExceptionHandler(ServiceException.class)
17
    public AjaxResult handleServiceException(ServiceException e) {
18
        return AjaxResult.error(e.getCode(), e.getMessage());
19
    }
20
}

展开收起

生产项目最好为错误分配稳定的业务码，不要让前端根据中文消息判断流程。日志中记录详细上下文，响应中只返回用户可理解且不泄露内部结构的信息。

10. CORS、CSRF 与无状态接口#

关闭 CSRF 并不意味着可以忽略安全，它依赖于“认证信息放在自定义请求头中，浏览器不会像 Cookie 那样自动附带”的前提。如果以后改用 Cookie 保存 Token，就要重新评估 CSRF 防护。

CORS 也不是权限控制。它只限制浏览器中的跨源读取，脚本、移动端和命令行客户端不受同样限制。因此任何业务接口都必须在服务端完成认证和授权。

11. 一次安全请求的完整路径#

以“修改地址”为例，请求链可以按以下顺序理解：

CORS 过滤器处理来源和预检请求；
JWT 过滤器从请求头恢复登录身份；
URL 规则判断请求是否需要认证；
Controller 使用 @Valid 校验请求结构；
@PreAuthorize 判断当前用户是否具备功能权限；
Service 校验地址是否属于当前用户；
Mapper 使用用户 ID 和资源 ID 完成条件更新；
全局异常处理器把失败转换为统一响应；
操作日志记录结果，但避免记录 Token、密码等敏感字段。

安全是链路属性，而不是某个注解的属性。只有每层职责清楚，才能在接口增长时持续维护边界。

12. 实践检查清单#

未显式放行的接口是否默认要求认证；
JWT 失效、Redis 会话失效和用户禁用是否都能拒绝请求；
新增接口是否配置了对应方法权限；
所有按 ID 修改、删除、下载的接口是否校验资源归属；
Controller 是否使用专用 DTO，避免实体字段被越权写入；
参数错误、业务错误和系统错误是否使用可区分的错误码；
日志是否脱敏，是否避免输出 Token、密码和完整身份证号；
是否覆盖未登录、无权限、跨用户访问、非法参数和重复提交测试。

13. 小结#

Spring Security 提供了认证与授权骨架，Bean Validation 提供了协议层校验能力，但真正可靠的接口还需要业务层资源归属检查和数据库条件约束。把过滤链、方法权限、DTO 校验、业务规则和统一异常串起来，才是一次请求完整的安全边界。

Spring AOP 代理与事务传播机制

Sun, 07 Jun 2026 00:00:00 GMT

项目中的 @Log、@DataScope、@RateLimiter 和 @Transactional 看起来只是注解，真正执行功能的是 Spring AOP 创建的代理。代理在目标方法前后插入通用逻辑，让业务代码不用重复编写日志、权限、限流和事务模板。

1. AOP 解决横切逻辑#

订单、用户、异常工单的接口都需要操作日志。如果每个方法手写相同代码，会出现大量重复：

1
long start = System.currentTimeMillis();
2
try {
3
    Object result = doBusiness();
4
    saveLog("SUCCESS", System.currentTimeMillis() - start);
5
    return result;
6
} catch (Exception e) {
7
    saveLog("FAILED", System.currentTimeMillis() - start);
8
    throw e;
9
}

AOP 把共同逻辑抽到切面，业务方法只声明意图：

1
@Log(title = "用户异常反馈",
2
     businessType = BusinessType.INSERT)
3
@PostMapping("/feedback")
4
public AjaxResult feedback(...) {
5
    return success(service.submitUserExceptionFeedback(dto));
6
}

切面读取注解内容，在方法执行前记录参数，执行后记录结果，异常时记录失败信息。

2. 切点、通知和连接点#

1
@Aspect
2
@Component
3
public class OperationLogAspect {
4
    @Pointcut("@annotation(com.ahebai.common.annotation.Log)")
5
    public void logPointcut() {
6
    }
7

8
    @Around("logPointcut()")
9
    public Object around(ProceedingJoinPoint point)
10
            throws Throwable {
11
        long start = System.currentTimeMillis();
12
        try {
13
            Object result = point.proceed();
14
            saveSuccess(point, result,
15
                    System.currentTimeMillis() - start);
16
            return result;
17
        } catch (Throwable e) {
18
            saveFailure(point, e);
19
            throw e;
20
        }
21
    }
22
}

展开收起

@Pointcut 选择哪些方法需要增强，@Around 定义增强内容，point.proceed() 才是真正调用目标方法。忘记调用 proceed，业务方法就不会执行；调用两次则会重复执行业务。

切面中捕获异常后必须重新抛出，否则上层会认为方法成功，事务也可能提交。

3. JDK 代理和 CGLIB#

Spring 常用两种代理：

代理方式	依据	特点
JDK 动态代理	接口	代理对象实现相同接口
CGLIB	类继承	生成目标类子类

Service 使用接口时通常可以采用 JDK 代理；没有接口时 Spring 可以使用 CGLIB。两者都只能拦截经过代理对象的可代理方法，private 方法和某些 final 方法不能按普通方式增强。

调用方应依赖 Service 接口，而不是强制转换成实现类，否则 JDK 代理场景下可能出现类型转换问题。

4. 自调用为什么绕过代理#

1
@Service
2
public class OrderService {
3
    public void process() {
4
        saveWithTransaction();
5
    }
6

7
    @Transactional
8
    public void saveWithTransaction() {
9
        mapper.insert(...);
10
    }
11
}

外部调用 process() 时经过代理，但 process 内部的 saveWithTransaction() 等价于 this.saveWithTransaction()，目标对象直接调用自己，没有再次经过代理，事务注解可能不生效。

更清晰的做法是把事务放在外部业务入口：

1
@Transactional
2
public void process() {
3
    mapper.insert(...);
4
}

或者把内部动作移动到另一个 Service，由 Spring 注入后调用。为了一个注解强行从容器获取自身代理，会让依赖关系更难理解。

5. @Transactional 的执行过程#

1
Controller 调用 Service 代理
2
  -> TransactionInterceptor 读取事务属性
3
  -> 从 DataSource 获取连接
4
  -> 关闭自动提交并绑定到当前线程
5
  -> 执行 Service 与多个 Mapper
6
  -> 正常返回：提交
7
  -> 匹配异常：回滚
8
  -> 释放连接

同一线程内的 MyBatis 操作会使用事务上下文中的连接，因此订单、支付记录和过程日志可以一起提交或回滚。

6. 回滚规则#

Spring 默认对运行时异常和 Error 回滚，对受检异常的默认行为不同。项目常写：

1
@Transactional(rollbackFor = Exception.class)
2
public HyDeliveryOrder createUserDeliveryOrder(...) {
3
}

这表示包括受检异常在内的 Exception 都触发回滚。仍需注意，方法内部 catch 后不再抛出的异常不会到达事务拦截器。

业务校验应尽量发生在写数据库之前，减少已经持锁后才失败的情况。

7. 传播行为解决嵌套调用#

最常见的 REQUIRED 表示加入已有事务：

1
订单 Service 开启事务
2
  -> 支付记录 Service 加入同一事务
3
  -> 过程日志 Service 加入同一事务

REQUIRES_NEW 会暂停外层事务并创建新事务。它适合必须独立保存的审计信息，但若过程日志描述的是订单成功节点，独立提交可能留下与回滚订单矛盾的记录。

SUPPORTS 在有事务时加入，没有时以非事务运行；MANDATORY 要求调用方必须已经开启事务。传播行为不是性能选项，而是数据一致性语义。

8. 隔离级别与并发现象#

数据库隔离级别处理脏读、不可重复读和幻读。订单状态更新更常遇到的是“两个请求都读到相同旧值，然后后写覆盖前写”。

可以使用条件更新或乐观锁：

1
update hy_delivery_order
2
set order_status = 'DELIVERING',
3
    version = version + 1
4
where order_id = #{orderId}
5
  and order_status = 'WAIT_DISPATCH'
6
  and version = #{version}

受影响行数为 0 表示数据已变化，Service 应重新读取并提示用户。提高隔离级别并不一定是最合适的解决方案，它可能增加锁竞争。

9. 事务范围应该多大#

事务应覆盖一个必须共同成功的本地业务动作，但不要包含无关的慢操作：

1
@Transactional
2
public void updateOrder() {
3
    validate();
4
    mapper.update(...);
5
    processLogMapper.insert(...);
6
    // 不适合在这里等待几十秒的外部接口
7
}

长事务会占用数据库连接和锁。大文件上传、第三方 HTTP 调用和复杂计算可以在事务前准备，或者通过状态表与事件拆开。

10. 数据库事务无法回滚第三方请求#

1
@Transactional
2
public void sendAndUpdate() {
3
    wechatClient.sendMessage(...);
4
    notificationMapper.updateSuccess(...);
5
}

若微信已发送成功，数据库更新失败，事务回滚也收不回消息。可以先在本地事务中写待发送事件，提交后由异步消费者调用微信，再更新发送结果。

对大疆创建任务这类不可随意重复的动作，还需要稳定业务请求号、第三方状态查询与人工补偿入口。

11. 多个切面的执行顺序#

一个方法可能同时经过权限、日志、限流和事务切面。可以通过 @Order 明确顺序，例如：

1
权限检查
2
  -> 限流
3
  -> 操作日志开始
4
  -> 事务开始
5
  -> 业务方法
6
  -> 事务提交/回滚
7
  -> 操作日志结束

日志若需要准确记录事务是否提交，应理解它位于事务切面的外部还是内部。顺序不明确时，可能记录“成功”后事务才提交失败。

12. AOP 的使用边界#

适合放入切面的逻辑通常具有这些特点：跨多个模块、与单个业务无关、可以通过方法上下文获得所需信息。

订单状态校验、退款金额计算不适合藏在通用切面，因为它们属于明确业务规则。切面过多会让方法源码看起来简单，运行时却有大量隐式行为，排查困难。

13. 本篇小结#

AOP 的核心不是注解，而是代理在方法边界插入行为。事务正是一种特殊的 AOP 增强。理解代理对象、自调用、传播行为和外部系统边界以后，才能判断 @Transactional 为什么生效、为什么失效，以及哪些一致性问题根本不能靠数据库事务解决。

Spring Bean 生命周期与自动配置原理

Thu, 04 Jun 2026 00:00:00 GMT

在 Spring Boot 项目里，我们很少手动 new Controller() 或 new Service()，但这些对象并不是凭空出现的。Spring 容器负责发现类、保存定义、创建实例、注入依赖、执行初始化回调，并在应用关闭时完成销毁。

理解 Bean 生命周期以后，很多问题会变得清楚：为什么某个 Service 注入为空、为什么 @PostConstruct 能访问 Mapper、为什么循环依赖危险，以及自动配置为什么有时生效、有时不生效。

1. 从启动类开始扫描#

1
@SpringBootApplication
2
public class UavApplication {
3
    public static void main(String[] args) {
4
        SpringApplication.run(UavApplication.class, args);
5
    }
6
}

SpringApplication.run 会创建应用上下文。@SpringBootApplication 中的组件扫描从启动类所在包向下查找 @Component、@Service、@RestController 和 @Configuration 等组件。

扫描阶段并不会立刻执行业务方法，而是先把类转换成 BeanDefinition。BeanDefinition 类似一张创建说明，记录 Bean 类型、名称、作用域、是否懒加载和构造参数。

如果启动类放在过深的包中，其他模块就可能不在默认扫描范围。当前启动类位于 com.ahebai 根包，因此各 Maven 模块中的 com.ahebai.* 组件都可以被发现。

2. Bean 生命周期的主要阶段#

可以把单例 Bean 的创建过程简化为：

1
扫描或注册 BeanDefinition
2
  -> 选择构造器并实例化
3
  -> 属性填充与依赖注入
4
  -> Aware 接口回调
5
  -> BeanPostProcessor 初始化前处理
6
  -> @PostConstruct / afterPropertiesSet / initMethod
7
  -> BeanPostProcessor 初始化后处理
8
  -> 必要时返回代理对象
9
  -> Bean 可以被业务代码使用
10
  -> 容器关闭时执行销毁回调

“实例化”和“初始化”不是同一步。实例化只是得到 Java 对象，依赖注入完成后才进入初始化回调。因此 @PostConstruct 中可以使用已经注入的 Mapper 或 Redis 组件。

3. 项目中的 @PostConstruct#

系统参数服务会在启动时加载配置缓存：

1
@Service
2
public class SysConfigServiceImpl
3
        implements ISysConfigService {
4

5
    @Autowired
6
    private SysConfigMapper configMapper;
7

8
    @Autowired
9
    private RedisCache redisCache;
10

11
    @PostConstruct
12
    public void init() {
13
        loadingConfigCache();
14
    }
15
}

展开收起

执行 init() 时，configMapper 和 redisCache 已完成注入。方法读取数据库配置并写入 Redis，让业务请求到来前就可以使用缓存。

初始化方法应尽量短且可预测。若它长时间请求外部服务，整个应用启动都会被阻塞；若异常直接抛出，Bean 创建失败，应用上下文通常也无法完成启动。非关键数据可以考虑延迟加载，关键初始化则应记录清晰错误并快速失败。

4. 构造器注入发生在什么时候#

1
@Service
2
public class OrderQueryService {
3
    private final HyDeliveryOrderMapper orderMapper;
4

5
    public OrderQueryService(
6
            HyDeliveryOrderMapper orderMapper) {
7
        this.orderMapper = orderMapper;
8
    }
9
}

Spring 在实例化 OrderQueryService 前必须先找到或创建 HyDeliveryOrderMapper。依赖通过构造器一次传入，对象创建后字段保持不可变。

字段注入则是先调用无参构造器，再通过反射设置字段。构造器注入更容易在普通单元测试中使用，也会更早暴露缺少依赖的问题。

如果只有一个构造器，现代 Spring 不要求再写 @Autowired。多个构造器同时存在时，需要明确告诉容器使用哪一个。

5. @Bean 适合创建第三方对象#

无法修改源码的第三方类不能添加 @Component，可以在配置类中创建：

1
@Configuration
2
public class SecurityConfig {
3
    @Bean
4
    public BCryptPasswordEncoder bCryptPasswordEncoder() {
5
        return new BCryptPasswordEncoder();
6
    }
7
}

@Bean 方法的返回值进入容器，其他组件就能注入 BCryptPasswordEncoder。方法名默认成为 Bean 名称，返回类型用于按类型匹配。

配置方法也可以直接声明依赖：

1
@Bean
2
public SqlSessionFactory sqlSessionFactory(
3
        DataSource dataSource) throws Exception {
4
    SqlSessionFactoryBean factory =
5
            new SqlSessionFactoryBean();
6
    factory.setDataSource(dataSource);
7
    return factory.getObject();
8
}

Spring 在调用方法前先解析 DataSource，不需要配置类手动从容器取对象。

6. BeanPostProcessor 与代理对象#

事务、AOP 和部分注解能力都依赖 Bean 后处理器。真实 Service 完成初始化后，后处理器可能返回一个代理对象：

1
Controller 注入的对象
2
  != 原始 HyDeliveryOrderServiceImpl
3
  = 带事务拦截器的代理

调用 @Transactional 方法时，代理先开启事务，再调用目标对象，最后提交或回滚。若绕过代理直接调用原始对象，相应增强就不会执行。

这也是为什么不要在配置阶段随意手动 new HyDeliveryOrderServiceImpl()：手动对象没有经过容器生命周期，自然也没有依赖注入、事务和切面。

7. 作用域与默认单例#

Spring Service 默认是单例：整个应用上下文只有一个实例。因此 Service 不应该把某个请求的订单 ID、用户 ID 或临时列表保存在成员字段中。

错误示例：

1
@Service
2
public class OrderService {
3
    private Long currentUserId;
4

5
    public List<Order> list() {
6
        currentUserId = SecurityUtils.getUserId();
7
        return mapper.selectByUserId(currentUserId);
8
    }
9
}

多个请求共享同一个字段，会互相覆盖。请求数据应保存在方法局部变量中，或者由线程安全的请求上下文提供。

常见作用域还有 prototype、request 和 session，但无状态后端通常让 Controller 与 Service 保持单例和无状态。

8. 循环依赖说明了什么#

1
OrderService -> NotificationService
2
NotificationService -> OrderService

循环依赖意味着两个对象都无法独立完成创建。部分字段注入场景下 Spring 曾能通过提前暴露对象解决，但构造器循环无法创建，而且代理、事务混入后行为更难预测。

更好的处理方式是重新划分职责：

把共同逻辑抽到第三个服务；
由上层编排 Service 依次调用两者；
使用领域事件降低直接依赖；
让通知接收订单 DTO，而不是反向调用订单 Service 查询所有内容。

不要把 @Lazy 当作默认解决方案，它只推迟暴露设计问题。

9. 自动配置如何判断是否生效#

Spring Boot 自动配置大量使用条件注解：

1
@Configuration
2
@ConditionalOnClass(RedisConnectionFactory.class)
3
@ConditionalOnMissingBean(RedisTemplate.class)
4
public class RedisAutoConfiguration {
5
    // 创建默认 RedisTemplate
6
}

含义是：classpath 中存在相关类，并且用户没有自己提供 RedisTemplate 时，才创建默认 Bean。项目一旦声明自己的同类型 Bean，默认配置就会“让位”。

常见条件包括：

条件	含义
`@ConditionalOnClass`	classpath 存在指定类
`@ConditionalOnMissingBean`	容器中还没有指定 Bean
`@ConditionalOnProperty`	配置项满足条件
`@ConditionalOnWebApplication`	当前是 Web 应用

自动配置不是扫描所有类后盲目创建，而是根据环境逐项判断。

10. 为什么项目排除默认数据源配置#

1
@SpringBootApplication(
2
        exclude = { DataSourceAutoConfiguration.class })
3
public class UavApplication {
4
}

项目使用 Druid、主从数据源和动态数据源，自行在 DruidConfig 中创建 DataSource。若默认数据源与自定义配置同时生效，可能出现多个候选 Bean、连接属性读取错误或 MyBatis 注入了错误数据源。

排除自动配置表示这一块完全由项目负责。代价是连接池、属性绑定、健康检查等细节也需要自己保证正确。

11. Starter 与自动配置的关系#

Starter 本质上是依赖集合，例如 Web Starter 把 Spring MVC、JSON 和内置容器需要的依赖组合起来。自动配置模块再根据这些依赖提供默认 Bean。

可以把关系记为：

1
Starter 解决“需要引入哪些依赖”
2
自动配置解决“这些依赖默认怎样创建对象”
3
application.yml 解决“对象使用哪些参数”
4
业务配置类解决“项目如何覆盖默认行为”

如果团队多个项目都需要相同的第三方平台客户端，可以把配置属性、客户端和条件配置封装成内部 Starter，而不是复制多份代码。

12. 排查 Bean 创建问题#

遇到 NoSuchBeanDefinitionException 或注入冲突时，可以按顺序检查：

类是否位于组件扫描范围；
是否添加正确组件注解；
接口是否真的有实现类；
条件注解是否满足；
是否出现多个同类型 Bean，需要 @Qualifier 或 @Primary；
配置类是否被扫描或导入；
初始化方法是否抛出异常导致 Bean 创建失败；
是否手动 new 了本应由容器管理的对象。

开启 Spring Boot 条件评估报告，可以看到某个自动配置为什么匹配或没有匹配，比只观察最终异常更容易定位。

13. 本篇小结#

Bean 生命周期描述了对象从定义到销毁的全过程，自动配置则是在容器创建阶段根据条件批量注册合理默认值。组件扫描、依赖注入、初始化回调和代理增强并不是互相独立的注解技巧，而是一条连续的容器工作链路。

Spring Boot 框架与项目分层实践：从目录结构到一次请求的完整链路

Mon, 01 Jun 2026 00:00:00 GMT

刚开始接触 Spring Boot 时，很容易把它理解成“写接口的框架”：加一个 @RestController，写一个 @GetMapping，浏览器就能拿到 JSON。真正进入完整项目以后才会发现，接口只是最外层，背后还有容器、自动配置、依赖注入、安全过滤器、业务事务、数据访问、缓存和异常处理。

本篇结合无人机配送管理平台，梳理 Spring Boot 在项目中到底承担什么角色，各个目录为什么这样划分，以及一次请求如何从 HTTP 进入数据库再返回前端。

1. Spring、Spring MVC 和 Spring Boot 的关系#

这三个名称经常同时出现，但职责并不相同：

名称	主要作用
Spring Framework	提供 IoC、依赖注入、AOP、事务等基础能力
Spring MVC	提供 Web 请求映射、参数绑定、响应转换等能力
Spring Boot	约定项目启动方式，组织自动配置、Starter 和运行环境

Spring Boot 没有取代 Spring，而是降低了 Spring 项目的配置成本。它根据依赖和配置推断需要创建哪些 Bean，并内置 Web 容器，让应用可以通过一个 main 方法直接运行。

可以把三者的关系理解为：

1
Spring Boot
2
  ├─ 组织和自动配置 Spring Framework
3
  ├─ 自动配置 Spring MVC
4
  ├─ 集成 Tomcat、Jackson、数据源等组件
5
  └─ 提供统一的配置、启动和部署方式

当前项目使用 Java 17、Spring Boot 4.0.6 和 MyBatis 4.0.1，并通过 Maven 父工程统一管理版本。

2. 项目的多模块目录#

项目不是单一目录，而是 Maven 聚合工程：

1
ahebai-uav-delivery-manage-new/
2
├─ pom.xml                 父工程，统一版本与模块声明
3
├─ uav-admin/              Web 服务入口
4
├─ uav-common/             通用返回、异常、注解和工具类
5
├─ uav-framework/          Security、Token、Redis、数据源等框架能力
6
├─ uav-system/             用户、角色、菜单、字典等系统模块
7
├─ uav-quartz/             Quartz 定时任务模块
8
├─ uav-generator/          MyBatis 代码生成模块
9
└─ uav-manage/             无人机配送业务模块

父工程的 <dependencyManagement> 负责统一版本，<modules> 决定构建哪些子模块。子模块只声明自己真正依赖的模块，例如 uav-manage 依赖 uav-common 和 uav-framework，uav-admin 再把系统、框架、任务与业务模块组装成最终应用。

这种结构的意义是把“可以复用的基础能力”和“当前项目的业务能力”分开：

更换配送业务时，不需要重写登录、分页和全局异常；
修改业务表时，不会直接影响代码生成器或系统菜单模块；
启动模块只负责装配，不需要堆放所有业务代码。

3. 启动类做了什么#

应用入口位于 uav-admin：

1
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
2
public class UavApplication {
3
    public static void main(String[] args) {
4
        SpringApplication.run(UavApplication.class, args);
5
    }
6
}

@SpringBootApplication 可以看成三个注解的组合：

1
@SpringBootConfiguration  当前类是配置入口
2
@EnableAutoConfiguration 根据依赖和条件加载自动配置
3
@ComponentScan           扫描当前包及其子包中的组件

启动类位于 com.ahebai 根包，因此依赖模块中位于 com.ahebai.* 下的 Controller、Service、配置类和组件都能被扫描到。

项目排除了默认数据源自动配置，是因为 uav-framework 中使用 Druid 和动态数据源配置自行创建数据源。排除自动配置不代表不使用 Spring Boot，而是告诉框架：“这一部分由项目接管”。

4. 一个业务模块内部有哪些目录#

以 uav-manage 为例，它不是简单按文件类型堆放，而是形成一条清晰的业务调用链：

1
uav-manage/
2
└─ src/main/
3
   ├─ java/com/ahebai/manage/
4
   │  ├─ controller/
5
   │  │  ├─ admin/         管理端接口
6
   │  │  └─ user/          小程序用户端接口
7
   │  ├─ service/          Service 接口
8
   │  │  └─ impl/          业务实现
9
   │  ├─ mapper/           MyBatis Mapper 接口
10
   │  ├─ domain/           数据库实体
11
   │  │  ├─ dto/           请求参数对象
12
   │  │  └─ vo/            返回对象
13
   │  ├─ dji/              大疆平台适配
14
   │  ├─ task/             定时任务入口
15
   │  ├─ exception/        业务专用异常
16
   │  └─ utils/            当前模块工具
17
   └─ resources/
18
      └─ mapper/manage/    MyBatis XML 与 SQL

展开收起

目录结构不是强制规范，但它表达了依赖方向。正常情况下，请求从 Controller 进入 Service，再由 Service 调用 Mapper；Mapper 不应该反过来依赖 Service，Service 也不应该依赖 Controller。

5. Controller 层：HTTP 与业务的边界#

Controller 负责理解 HTTP，但不应该承担完整业务。

它适合处理：

URL 与请求方法映射；
路径、查询和请求体参数接收；
@PreAuthorize 权限声明；
开启分页；
调用 Service；
返回 AjaxResult 或 TableDataInfo。

1
@RestController
2
@RequestMapping("/manage/user/exception-ticket")
3
public class UserHyExceptionTicketController extends BaseController {
4
    @PostMapping("/feedback")
5
    public AjaxResult feedback(@RequestBody UserExceptionFeedbackDto dto) {
6
        return success(exceptionTicketService.submitUserExceptionFeedback(dto));
7
    }
8
}

Controller 不应该直接写 SQL，也不应该在里面完成退款、改订单、写日志等多步操作。否则业务规则会和接口协议绑死，定时任务或其他入口也无法复用。

6. Service 层：真正的业务中心#

Service 负责回答“这件事能不能做，以及做了以后哪些数据必须一起改变”。

例如异常退款不是单表更新，而是：

1
校验工单状态
2
  -> 新增退款支付记录
3
  -> 更新原订单状态
4
  -> 更新异常工单状态
5
  -> 新增订单过程日志

这些步骤应该放在同一个 Service 方法和事务中。Controller 只需要调用“取消退款”这个动作，不需要知道内部修改了几张表。

项目把 Service 分为接口和实现：

1
IHyDeliveryOrderService
2
  └─ HyDeliveryOrderServiceImpl

接口可以隔离调用方和实现、便于替换实现或测试，也符合 Spring 通过代理添加事务和切面的方式。不过并不是所有简单类都必须为了形式建立接口，是否抽象仍应由复用、替换和边界需求决定。

7. Mapper 层：Java 方法与 SQL 的连接点#

Mapper 接口声明数据访问能力，Mapper XML 保存 SQL 和结果映射：

1
public interface HyDeliveryOrderMapper {
2
    HyDeliveryOrder selectHyDeliveryOrderByOrderId(Long orderId);
3
    int insertHyDeliveryOrder(HyDeliveryOrder order);
4
}

1
<select id="selectHyDeliveryOrderByOrderId"
2
        resultMap="HyDeliveryOrderResult">
3
    select ... from hy_delivery_order where order_id = #{orderId}
4
</select>

@MapperScan("com.ahebai.**.mapper") 会扫描 Mapper 接口，MyBatis 为它们创建代理对象。调用 Mapper 方法时，代理根据方法名找到 XML 中同名语句，再通过 SqlSessionFactory 使用数据源执行 SQL。

Mapper 适合表达查询和持久化，不适合决定“当前用户是否有权退款”。业务权限属于 Service，SQL 则可以继续承担数据范围和条件更新等数据库最擅长的工作。

8. Entity、DTO 和 VO 为什么要分开#

三个对象看起来字段相似，但面对的边界不同：

对象	面向对象	作用
Entity / Domain	数据库	描述表字段和持久化结果
DTO	请求方	只接收某个动作允许输入的字段
VO	响应方	只返回页面真正需要的数据

例如用户资料实体包含状态、删除标记和登录失败次数，但修改资料 DTO 不应该允许用户提交这些字段；凭证实体包含真实存储路径，返回 VO 则只给出 hasImage 和鉴权图片接口所需的凭证 ID。

如果所有地方都直接使用 Entity，接口很容易出现“过度写入”和“过度返回”。对象分层本质上是在保护边界，而不只是增加文件数量。

9. IoC 与依赖注入#

普通 Java 代码通常主动创建依赖：

1
OrderService service = new OrderService();

Spring 则由 IoC 容器负责创建对象和维护关系。带有以下注解的类会成为 Bean：

1
@Component       通用组件
2
@Service         业务服务
3
@Repository      数据访问组件
4
@RestController  Web 控制器
5
@Configuration   配置类
6
@Bean            配置类中手动创建的对象

Controller 依赖 Service、Service 依赖 Mapper，Spring 在启动时把对应 Bean 注入进去。项目当前较多使用字段注入：

1
@Autowired
2
private IHyDeliveryOrderService deliveryOrderService;

新代码也可以优先使用构造器注入：

1
private final IHyDeliveryOrderService deliveryOrderService;
2

3
public OrderController(IHyDeliveryOrderService deliveryOrderService) {
4
    this.deliveryOrderService = deliveryOrderService;
5
}

构造器注入可以让依赖保持不可变，更方便单元测试，也能在对象创建时立即发现缺失依赖。

10. 一次请求的完整生命周期#

以一个需要登录的订单详情请求为例，大致会经过：

1
客户端 HTTP 请求
2
  -> 内置 Tomcat 接收连接
3
  -> CORS、JWT 等 Servlet Filter
4
  -> Spring Security 建立认证上下文
5
  -> DispatcherServlet
6
  -> HandlerMapping 找到 Controller 方法
7
  -> 参数解析与校验
8
  -> Controller
9
  -> Service 代理（事务、日志等 AOP）
10
  -> Mapper 代理
11
  -> SqlSession / DataSource / MySQL
12
  -> Service 组装业务结果
13
  -> Jackson 序列化 JSON
14
  -> HTTP 响应

如果中途抛出异常，@RestControllerAdvice 会接管响应；如果方法带有 @Transactional，事务代理会根据异常决定提交或回滚。

理解这条链路以后，排查问题会更有方向：

请求没有进入 Controller：检查路径、方法、过滤器和 Security；
Controller 参数为空：检查 Content-Type、字段名和参数注解；
Service 没有回滚：检查事务代理和异常类型；
Mapper 找不到语句：检查 Mapper 扫描、XML 路径与 statement id；
数据正确但 JSON 不对：检查 VO、Jackson 和日期配置。

11. 自动配置与显式配置#

Spring Boot 的自动配置并不是“什么都不配”，而是根据条件提供默认值。例如存在 Web Starter 时配置 Spring MVC 和内置 Tomcat，存在 Jackson 时配置 JSON 转换器。

项目又通过配置类显式接管特殊需求：

SecurityConfig：无状态安全链、JWT 过滤器与匿名地址；
DruidConfig：主从数据源和连接池；
MyBatisConfig：别名包、Mapper XML 和 SqlSessionFactory；
RedisConfig：缓存序列化；
ThreadPoolConfig：异步线程池；
ResourcesConfig：静态资源和拦截器；
ApplicationConfig：Mapper 扫描与 AOP 代理暴露。

自动配置适合通用默认值，显式配置适合项目特有规则。两者不是竞争关系，而是“约定优先，需要时覆盖”。

12. application.yml 与配置对象#

application.yml 保存服务端口、日志级别、上传限制、Redis、Token、MyBatis 等配置，并通过：

1
spring:
2
  profiles:
3
    active: druid

加载 application-druid.yml 中的数据源配置。

代码可以使用 @Value 读取单个值，也可以通过 @ConfigurationProperties 绑定一组配置：

1
@ConfigurationProperties(prefix = "dji.api")
2
public class DjiApiProperties {
3
    private String baseUrl;
4
    private Duration connectTimeout;
5
    private Duration requestTimeout;
6
}

成组配置更适合类型校验和集中管理。数据库密码、Token 密钥、微信 Secret 与第三方 SecretKey 不应直接提交真实值，可以使用环境变量或部署平台的密钥管理服务注入：

1
wechat:
2
  mini-program:
3
    app-id: ${WECHAT_APP_ID:}
4
    secret: ${WECHAT_APP_SECRET:}

13. Spring Security 在哪里生效#

项目使用无 Session 的 Token 模式：

1
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)

JWT 过滤器在用户名密码过滤器之前执行，从请求头读取 Token，恢复 LoginUser 并写入安全上下文。之后 Controller 和 Service 才能调用 SecurityUtils.getUserId()。

安全规则分为两层：

URL 层判断接口是否需要认证；
@PreAuthorize 判断当前用户是否拥有具体权限。

此外，用户只能操作自己的订单和地址属于对象级权限，需要在 Service 中检查资源归属。登录、菜单权限和对象归属解决的是三个不同问题。

14. 全局异常为什么必要#

业务代码不需要在每个 Controller 中重复 try-catch。Service 可以抛出 ServiceException，全局异常处理器统一转换为 AjaxResult：

1
@RestControllerAdvice
2
public class GlobalExceptionHandler {
3
    @ExceptionHandler(ServiceException.class)
4
    public AjaxResult handleServiceException(ServiceException e) {
5
        return AjaxResult.error(e.getMessage());
6
    }
7
}

项目还分别处理权限不足、请求方法错误、路径变量缺失、参数类型错误和参数校验异常。

业务异常和系统异常应该区分：

“订单已取消，不能再次支付”是可以展示给用户的业务异常；
数据库连接失败、空指针等属于系统异常，应记录完整日志，但生产响应不宜直接暴露堆栈和内部实现信息。

15. 事务为什么通常放在 Service#

@Transactional 依赖 Spring AOP 代理。请求进入代理方法时开启事务，正常结束时提交，出现符合条件的异常时回滚。

1
@Transactional(rollbackFor = Exception.class)
2
public HyDeliveryOrder mockPayUserDeliveryOrder(Long orderId) {
3
    // 支付记录、订单状态、过程日志必须一起成功
4
}

事务放在 Service，是因为 Service 知道一次完整业务动作涉及哪些 Mapper。Mapper 只看到单条 SQL，Controller 又不应该理解所有数据细节。

使用事务时还要注意：

同一个类中普通方法直接调用另一个事务方法，可能绕过代理；
捕获异常后不继续抛出，事务可能认为操作成功；
默认回滚规则与异常类型有关，项目使用 rollbackFor = Exception.class 明确范围；
数据库事务无法回滚已经发给微信或大疆的外部请求；
事务范围过大，会长时间占用连接和数据库锁。

16. AOP、过滤器和拦截器分别做什么#

三者都能处理“很多接口共同需要的逻辑”，但工作位置不同：

机制	主要位置	适合场景
Filter	Servlet 请求最外层	CORS、JWT、XSS、请求包装
Interceptor	Spring MVC Controller 前后	防重复提交、Handler 级检查
AOP Aspect	Spring Bean 方法调用	操作日志、数据权限、限流、事务

项目中的 LogAspect、DataScopeAspect、RateLimiterAspect 都属于 AOP。注解只是在方法上声明意图，真正的通用逻辑由切面统一完成。

17. 缓存与 Bean 生命周期#

系统参数 Service 使用 @PostConstruct 在 Bean 创建并完成依赖注入后加载配置到 Redis：

1
@PostConstruct
2
public void init() {
3
    loadingConfigCache();
4
}

读取参数时先查缓存，缓存没有再查数据库并回填。修改参数时同步更新缓存，删除时同时清理缓存。

这属于 Cache Aside 思路，但仍要注意数据库与缓存之间的短暂不一致。对于关键业务状态，不能因为接入 Redis 就默认缓存永远可靠；缓存更适合加速读取，数据库仍是最终事实来源。

18. 定时任务如何复用业务层#

Spring Bean 不只由 Controller 调用。Quartz 也可以按配置调用任务 Bean：

1
@Component("deliveryOrderTimeoutTask")
2
public class DeliveryOrderTimeoutTask {
3
    public void cancelTimeoutUnpaidOrders() {
4
        orderService.cancelTimeoutUnpaidOrders(15);
5
    }
6
}

任务类只负责触发，超时判断、状态更新和日志写入仍放在 Service。这样人工补偿、接口调用和定时调度能够复用同一业务规则。

报表快照也采用相同结构：Quartz 决定执行时间，Service 负责日报、周报、月报的统计口径与幂等落库。

19. Spring Boot 没有替我们完成什么#

Spring Boot 能自动创建很多基础设施，但不会自动保证业务正确：

@Transactional 不会自动决定事务应该包含哪些步骤；
@PreAuthorize 不会自动检查订单是否属于当前用户；
MyBatis 不会自动避免慢 SQL 和错误索引；
Redis 不会自动解决缓存一致性；
全局异常处理不会自动区分哪些信息可以暴露；
自动配置不会替项目选择正确的模块边界。

框架解决的是通用机制，开发者仍然要定义业务规则和数据边界。

20. 项目中常见的分层误区#

Controller 过重#

在 Controller 中查询多张表、修改状态并写日志，会导致业务无法复用，也难以统一事务。

Service 只是转发 Mapper#

简单 CRUD 可以很薄，但订单审核、退款等动作如果仍只是转发，业务校验就会散到前端或 Controller。

为每张表机械生成所有接口#

数据库表不等于公开资源。支付记录、过程日志等表可能只应该由业务动作生成，不一定需要开放通用新增和删除接口。

直接返回 Entity#

容易暴露存储路径、删除标记和内部字段，也让数据库字段变化直接影响接口契约。

只在前端限制状态和权限#

按钮隐藏不能阻止直接请求。状态前置条件、资源归属和字段白名单都必须由后端再次检查。

21. 完整示例：地址簿搜索接口#

前面分别介绍了各层，下面用真实的地址簿搜索把它们连起来。接口需求是：当前登录用户输入关键字，按船名、收货人或手机号搜索自己的有效地址。

请求形式：

1
GET /manage/user/user-address/search?keyword=海运
2
Authorization: Bearer <token>

期望响应只包含当前用户地址，默认地址排在最前，空关键字不执行模糊查询。

Controller 接收 HTTP 参数#

1
@RestController
2
@RequestMapping("/manage/user/user-address")
3
public class UserHyUserAddressController
4
        extends BaseController {
5

6
    @Autowired
7
    private IHyUserAddressService userAddressService;
8

9
    @GetMapping("/search")
10
    public AjaxResult search(
11
            @RequestParam(required = false) String keyword) {
12
        return success(
13
                userAddressService
14
                        .selectUserAddressSearchList(keyword));
15
    }
16
}

展开收起

@RestController 表示返回值直接写入响应体，并由 Jackson 转为 JSON。类上的 @RequestMapping 定义公共前缀，方法上的 @GetMapping 补充具体路径。

@RequestParam(required = false) 允许参数缺失，因此 Java 变量可能是 null。Controller 没有自己处理 null，也没有接收用户 ID，而是把业务判断交给 Service。

success(data) 来自 BaseController，最终生成统一的 AjaxResult。如果 Service 抛出 ServiceException，当前方法不会继续执行，异常会被全局处理器接管。

Service 处理空值和用户边界#

接口定义：

1
public interface IHyUserAddressService {
2
    List<HyUserAddress> selectUserAddressSearchList(
3
            String keyword);
4
}

实现：

1
@Service
2
@Transactional(readOnly = true)
3
public class HyUserAddressServiceImpl
4
        implements IHyUserAddressService {
5

6
    @Autowired
7
    private HyUserAddressMapper userAddressMapper;
8

9
    @Override
10
    public List<HyUserAddress> selectUserAddressSearchList(
11
            String keyword) {
12
        String searchKeyword =
13
                StringUtils.trimToEmpty(keyword);
14
        if (searchKeyword.isEmpty()) {
15
            return Collections.emptyList();
16
        }
17
        return userAddressMapper.selectUserAddressSearchList(
18
                SecurityUtils.getUserId(), searchKeyword);
19
    }
20
}

展开收起

trimToEmpty 同时处理 null、空字符串和只有空格的输入。空关键字直接返回空列表，避免 SQL 变成 like '%%' 后读取当前用户全部地址。

用户 ID 从 SecurityUtils 获取。JWT 过滤器已经在 Controller 之前恢复登录上下文，因此调用方不能通过查询参数搜索其他用户地址。

类级 @Transactional(readOnly = true) 表达这个 Service 默认执行读取操作。新增、修改和删除方法再使用方法级写事务覆盖它。只读事务既是意图说明，也可能帮助数据库或 ORM 做只读优化，但它不是权限控制手段。

Mapper 接口声明两个具名参数#

1
public interface HyUserAddressMapper {
2
    List<HyUserAddress> selectUserAddressSearchList(
3
            @Param("wxUserId") Long wxUserId,
4
            @Param("keyword") String keyword);
5
}

方法有两个简单参数，因此使用 @Param 明确它们在 XML 中的名称。XML 可以稳定引用 #{wxUserId} 和 #{keyword}，不依赖编译器是否保留 Java 参数名。

Spring 启动时，@MapperScan 找到这个接口，MyBatis 为它创建代理。Service 中注入的 userAddressMapper 实际是代理对象，而不是开发者手写的实现类。

Mapper XML 执行查询#

1
<select id="selectUserAddressSearchList"
2
        resultMap="HyUserAddressResult">
3
    <include refid="selectHyUserAddressVo" />
4
    where wx_user_id = #{wxUserId}
5
      and status = '0'
6
      and del_flag = '0'
7
      and (
8
          vessel_name like concat('%', #{keyword}, '%')
9
          or receiver_name like concat('%', #{keyword}, '%')
10
          or receiver_phone like concat('%', #{keyword}, '%')
11
      )
12
    order by is_default desc,
13
             update_time desc,
14
             create_time desc,
15
             address_id desc
16
</select>

展开收起

id 必须与 Mapper 方法名一致，resultMap 决定数据库下划线字段怎样映射为 Java 属性。<include> 复用公共 select 字段，避免列表和详情重复维护列名。

#{keyword} 使用预编译参数，不会把输入直接拼进 SQL。外层括号保证三个模糊条件整体受用户 ID、状态和删除标记限制；如果漏掉括号，SQL 的 AND/OR 优先级可能让其他用户满足手机号条件的记录被错误返回。

排序先按默认地址降序，再按更新时间、创建时间和主键降序。最后加入主键可以在时间相同的情况下保持稳定顺序。

响应怎样回到前端#

Mapper 通过 resultMap 生成 List<HyUserAddress>，Service 原样返回列表，Controller 包装成：

1
{
2
  "code": 200,
3
  "msg": "操作成功",
4
  "data": [
5
    {
6
      "addressId": 18,
7
      "vesselName": "海运号",
8
      "receiverName": "张三",
9
      "isDefault": "1"
10
    }
11
  ]
12
}

Jackson 根据 Java Bean 的 getter 生成 JSON。日期格式、时区和 null 字段策略可以通过 Spring Jackson 配置统一，而不需要每个 Controller 手工序列化。

这条完整链路可以概括为：

1
keyword 查询参数
2
  -> Spring MVC 参数绑定
3
  -> Controller 调用 Service
4
  -> Service 清理关键字并取得当前用户
5
  -> MyBatis 代理匹配 XML
6
  -> 预编译 SQL 查询 MySQL
7
  -> resultMap 构造对象列表
8
  -> AjaxResult 包装
9
  -> Jackson 输出 JSON

22. 如果接口报错，应从哪一层排查#

返回 401#

请求还没有进入 Controller。检查 Authorization 请求头、Token 是否过期、JWT 过滤器是否识别当前路径，以及登录接口写入 Redis 的用户缓存是否存在。

返回 404#

检查类级和方法级路径拼接、应用 context path，以及 Controller 是否位于启动类扫描包下。Controller 没被注册时，方法里的断点永远不会命中。

keyword 始终为空#

检查前端是否使用查询参数、参数名是否确实是 keyword。若前端发送 JSON 请求体，就需要 @RequestBody DTO，而不是 @RequestParam。

Mapper 提示找不到 statement#

检查四处是否一致：

1
Mapper 接口全限定名
2
  = XML namespace
3
Mapper 方法名
4
  = select/update/insert/delete 的 id
5
XML 是否位于 mybatis.mapperLocations 扫描路径
6
Mapper 接口是否在 @MapperScan 范围

SQL 能运行但返回了其他用户地址#

重点检查用户 ID 是否来自安全上下文，以及 OR 条件是否放在括号内。权限问题通常不是 Spring 注解失效，而是数据查询条件没有真正限制拥有者。

23. 参数校验还可以怎样完善#

当前搜索参数简单，手工 trim 足够。创建订单等复杂请求更适合 Jakarta Validation：

1
public class UserDeliveryOrderCreateDto {
2
    @NotBlank(message = "服务类型不能为空")
3
    private String serviceType;
4

5
    @NotBlank(message = "收货人不能为空")
6
    @Size(max = 50, message = "收货人不能超过50个字符")
7
    private String receiverName;
8

9
    @Pattern(
10
        regexp = "^1\\d{10}$",
11
        message = "手机号格式不正确")
12
    private String receiverPhone;
13
}

Controller 使用：

1
public AjaxResult create(
2
        @Valid @RequestBody UserDeliveryOrderCreateDto dto) {
3
    return success(orderService.createUserDeliveryOrder(dto));
4
}

Spring MVC 在进入方法前执行字段校验，失败时抛出 MethodArgumentNotValidException，项目全局异常处理器已经能提取字段错误并返回统一结果。

注解校验适合长度、格式和必填等结构规则；“快递订单必须有快递单号”“订单只能由当前用户修改”仍属于跨字段或数据库业务规则，应留在 Service。

24. 怎样为这条链路写测试#

Controller 测试关注 HTTP 契约，可以模拟 Service：

1
mockMvc.perform(get(
2
        "/manage/user/user-address/search")
3
        .param("keyword", "海运")
4
        .header("Authorization", token))
5
    .andExpect(status().isOk())
6
    .andExpect(jsonPath("$.code").value(200))
7
    .andExpect(jsonPath("$.data[0].vesselName")
8
            .value("海运号"));

Service 单元测试关注空关键字和当前用户 ID：

1
keyword = null      -> 返回空列表，不调用 Mapper
2
keyword = "   "     -> 返回空列表，不调用 Mapper
3
keyword = " 海运 "   -> Mapper 收到去空格后的“海运”
4
登录用户 ID = 12     -> Mapper 第一个参数必须是 12

Mapper 集成测试则使用测试数据库验证 SQL 括号、逻辑删除和排序：准备两个用户的相似地址，确保查询结果只属于当前用户，并且默认地址排在第一位。

把测试也按层拆分，失败时更容易判断是 HTTP 映射、业务规则还是 SQL 出现问题。

25. 本篇小结#

Spring Boot 项目的核心不是记住多少注解，而是理解对象由谁创建、请求经过哪些组件、每一层负责什么，以及通用机制与业务规则在哪里交汇。

从目录上看，Controller、Service、Mapper、DTO 和 VO 是分层；从运行过程看，过滤器、安全上下文、MVC、事务代理和 MyBatis 又组成了一条完整链路。只有把静态目录和动态调用过程放在一起理解，才能真正读懂一个 Spring Boot 项目，也才能知道新功能应该写在哪里。

Yore

十一节后工作日记

1. 先确定最终页面链路#

2. 用页面模型隔离接口字段#

3. 新增与编辑共用一个弹窗#

4. 从 Knife4j 文档整理接口边界#

5. 分页响应为什么没有 data#

6. 六张启用上限放在状态动作前#

7. 图片预览故障：fileId 不是 ossId#

8. Review：管理端如何恢复图片回显#

9. WST 首页的 API 封装#

10. 调试时如何证明链路已经恢复#

11. 本次工作的几个记录#

前端面试提问①

一、Vue 3 核心知识#

1. Vue 3 的响应式是怎样工作的？#

2. setup 的作用是什么？#

3. computed、watch 和 watchEffect 如何选择？#

二、CSS 选择器与层叠#

4. 常用选择器有哪些？#

5. 为什么不能只背“important 大于 ID 大于 class”？#

三、页面加载与性能#

6. 用户说页面很慢，你先做什么？#

7. defer、async 和预加载怎么用？#

四、技术选型如何回答#

8. 面试官问“你了解哪些新技术”，怎样避免堆名词？#

五、HTTP 状态码#

9. 高频状态码怎么区分？#

六、上传报错实战#

10. Axios ERR_NETWORK、ERR_CONNECTION_RESET 怎么排查？#

七、面试前快速复述#

前端项目面试提问①：从技术栈到业务实现

一、先把项目技术栈讲清楚#

二、无人机配送管理端#

1. 为什么选择 Vue 3 + Element Plus + Pinia？#

2. 动态路由是怎样加载的？隐藏按钮能保证安全吗？#

3. Axios 封装具体做了什么？#

4. 前端防重复提交等于接口幂等吗？#

5. 订单按钮、状态标签和操作流程如何保持一致？#

6. 地图和 ECharts 页面如何避免越用越卡？#

三、凭证查询与财务报表#

7. 用户快速切换单位和月份，旧请求覆盖新结果怎么办？#

8. 为什么把报表查询抽成 composable？#

四、无人机配送小程序#

9. uni-app 为什么还需要微信适配层？#

10. 多个请求同时 loading，怎么避免一个请求先结束就把提示关掉？#

11. 小程序上传图片成功后，为什么不能只保存临时路径？#

五、健身小程序#

12. TypeScript 给这个项目带来了什么？#

13. 本地训练记录和云端记录怎样合并？#

六、博客与内容工程#

14. 为什么博客使用 Astro，而管理端使用 Vue？#

15. 新增文章为什么不用手动改文章列表？#

16. 如果面试官要求你证明优化有效，怎么回答？#

七、一段可复述的项目介绍#

小程序开发日记⑨：微信开放接口与原生组件调用

1. 项目中使用的微信能力#

2. 为什么建立 utils/wx 适配层#

3. wx.login 与会话恢复#

4. 手机号能力必须由原生按钮触发#

5. 隐私授权与用户手势#

6. 订阅消息调用时机#

7. chooseAvatar 与昵称输入#

8. 图片选择、上传与预览#

9. 鉴权图片与文件系统#

10. 地图组件和定位接口#

11. 微信客服组件#

12. 分享能力#

13. 剪贴板能力#

14. 调用微信能力时总结出的规则#

14.1 区分函数 API 和组件开放能力#

14.2 授权失败不等于业务失败#

14.3 平台返回值必须再做业务适配#

14.4 注意生命周期与一次性凭证#

15. 本篇小结#

编辑表单的数据回显与提交：新增、修改和重提如何共用页面

1. 先明确三种模式#

2. 回显函数是接口到表单的适配器#

3. 日期时间回显#

4. 异步加载顺序#

5. 分页响应为什么没有 `data`#

7. 图片预览故障：`fileId` 不是 `ossId`#

2. 为什么建立 `utils/wx` 适配层#

3. `wx.login` 与会话恢复#

7. `chooseAvatar` 与昵称输入#