Go go-imap 的 UID 与消息序号为什么不能混用

在 github.com/emersion/go-imap/v2/imapclient 中，消息序号和 UID 都能放进 imap.NumSet，但它们代表的不是同一种编号：消息序号是当前选中邮箱里的位置，UID 是这个邮箱分配给邮件的标识。前者适合描述“当前列表里的第几封”，后者适合保存“下一次还要找同一封”。

官方文档：https://pkg.go.dev/github.com/emersion/go-imap/v2/imapclient

只要标识要跨请求、跨同步或跨程序重启保存，就优先使用 UID，并把邮箱名与 UIDValidity 一起保存；只在当前选中邮箱、当前列表快照内临时操作时，才使用消息序号。不要因为两个类型都能传给 Fetch 或 Store，就把它们当成可以互换的数字。

• 消息序号：当前选中邮箱中从 1 开始的列表位置，邮件被永久删除或列表变化后可能改变。
• UID：由单个邮箱分配的消息标识，通常用于再次定位同一封邮件，但不能脱离邮箱和 UIDValidity 单独解释。
• 代码表达：imap.SeqSetNum 创建序号集合，imap.UIDSetNum 创建 UID 集合。
• 排障重点：先看请求使用的是 SeqSet 还是 UIDSet，再看缓存是否绑定了正确的邮箱和 UIDValidity。

先分清两套编号：消息序号和 UID

选中一个邮箱后，IMAP 会给当前消息列表分配消息序号。假设列表中有三封邮件，它们暂时对应序号 1、2、3；这只是当前邮箱视图中的位置。UID 则是邮箱为邮件分配的标识，例如 101、205、309。UID 不要求连续，不能把 UID 205 推导成“第二封”或把它与另一个邮箱里的 205 当成同一封。

go-imap v2 把两种集合都抽象成 imap.NumSet，而文档明确说明 NumSet 可以是 SeqSet 或 UIDSet。这让 API 复用更方便，也让变量命名更重要：不要写成含糊的 numbers，而要保留 seqSet、uidSet 这样的语义。

为什么删信或新邮件到来后序号会失效

消息序号描述的是列表位置。当前列表中如果第 2 封被标记删除并执行永久清理，原来的第 3 封可能移动到序号 2；如果邮箱同步后前面出现了新邮件，后续位置也可能整体变化。因此，“我上次看到的序号 3”不能自然推出“现在还是同一封邮件”。

这也是批量处理最容易出错的地方：先搜索得到一组序号，等待其他同步动作完成，再用原集合去修改标记或读取正文，集合里的数字可能已经对应了别的邮件。序号并非错误，它只适合绑定在同一个选中状态和短生命周期里。

UID 也不是全局主键。它属于某个邮箱的 UID 空间，并且要结合 UIDValidity 判断缓存是否仍然有效。更稳妥的缓存键是“邮箱名 + UIDValidity + UID”，而不是只保存一个整数。

在 Go 代码里显式写出 SeqSet 和 UIDSet

下面的片段只演示集合的表达方式，不连接真实邮箱。当前选中邮箱里的第 1 封可以用 SeqSetNum 表示；已知 UID 101 和 205 时则用 UIDSetNum。两者都满足 imap.NumSet，但发送给服务器后语义不同。

package main

import (
	"fmt"

	"github.com/emersion/go-imap/v2"
)

func main() {
	// 序号只表达当前选中邮箱里的位置，适合短生命周期的列表操作
	seqSet := imap.SeqSetNum(1, 3)

	// UID 表达邮箱内的消息标识，适合从搜索结果或持久化记录继续定位
	uidSet := imap.UIDSetNum(101, 205)

	// 两个集合都能作为 NumSet 传给接收 NumSet 的 API，但不能互换含义
	var seqNumbers imap.NumSet = seqSet
	var uidNumbers imap.NumSet = uidSet
	fmt.Println("sequence:", seqNumbers.String())
	fmt.Println("uid:", uidNumbers.String())
}

示例输出的重点不是数字格式，而是变量的来源和生命周期：seqSet 来自当前列表位置，uidSet 来自邮箱的 UID 标识。给变量换一个名字并不会改变请求语义，所以应在函数签名、结构体字段和缓存记录中都保留这种区别。

Fetch、Store 和 Search 怎样选择集合

Client.Fetch 接收 imap.NumSet。需要读取当前列表中某几个位置时可以传 SeqSet；需要按已经确认的 UID 取邮件时传 UIDSet。读取命令的返回对象仍应带出消息自身的 UID，避免后续代码把返回顺序当作永久身份。

搜索时也要看意图。普通搜索结果可以通过 AllSeqNums 解释为序号；如果要把搜索结果交给后续的稳定处理，应使用 UIDSearch 并读取 AllUIDs。这样得到的不是“当前第几封”，而是可在同一 UID 空间中继续使用的标识集合。

package maildemo

import (
	"log"

	"github.com/emersion/go-imap/v2"
	"github.com/emersion/go-imap/v2/imapclient"
)

func findUIDs(c *imapclient.Client) (imap.UIDSet, error) {
	// UIDSearch 返回 UID 语义的搜索结果，适合交给后续稳定操作
	data, err := c.UIDSearch(&imap.SearchCriteria{
		Body: []string{"invoice"}, // 只示范搜索条件，真实业务应按需求组合
	}, nil).Wait()
	if err != nil {
		return imap.UIDSet{}, err
	}

	// AllUIDs 把结果解释成 UID；不要改用 AllSeqNums 再长期保存
	uids := data.AllUIDs()
	if len(uids) == 0 {
		return imap.UIDSet{}, nil
	}
	return imap.UIDSetNum(uids...), nil
}

func fetchByUID(c *imapclient.Client, uidSet imap.UIDSet) error {
	// UIDSet 作为 NumSet 表达稳定定位意图，FetchCommand 必须完整消费
	cmd := c.Fetch(uidSet, &imap.FetchOptions{Envelope: true})
	defer cmd.Close() // 即使读取中途出错，也要释放命令资源
	for {
		msg := cmd.Next()
		if msg == nil {
			break
		}
		_ = msg // 示例只关注集合类型，不展开邮件解析
	}
	return nil
}

var _ = log.Printf

这里的 Fetch 示例强调的是类型边界，不代表已经连接或运行过邮箱。实际项目中要处理命令的读取错误，并按文档要求完整消费 FetchCommand；如果函数的目标是长期同步，应同时记录选择邮箱返回的 UIDValidity。

删除或修改邮件时不要把两种集合混在一起

如果任务是“当前列表第 4 封加星”，短暂使用 imap.SeqSetNum(4) 可以成立，但前提是列表没有在请求前后被其他动作改变。如果任务是“把搜索得到的这些邮件移动、加标记或按 UID 删除”，则应沿用 UID 集合，并在能力允许时使用对应的 UID 命令。

UIDExpunge 接收 imap.UIDSet，并发送 UID EXPUNGE；官方文档还注明该命令需要 IMAP4rev2 或 UIDPLUS。不能把一个序号集合强行转换为 UID 集合，也不能把 UID 的整数值直接传给只表达序号的业务层。

func expungeByUID(c *imapclient.Client, uids imap.UIDSet) error {
	// 调用方必须确认 UID 属于当前选中的邮箱和有效的 UIDValidity
	cmd := c.UIDExpunge(uids)
	if _, err := cmd.Collect(); err != nil {
		return err
	}
	return nil
}

func markCurrentPosition(c *imapclient.Client, position uint32) error {
	// 该函数只接受当前列表位置，避免调用方误把 UID 当序号传入
	seqSet := imap.SeqSetNum(position)
	flags := &imap.StoreFlags{
		Op:     imap.StoreFlagsAdd,
		Flags:  []imap.Flag{imap.FlagFlagged}, // 示例只添加 Flagged 标记
		Silent: true,                          // 不要求响应重复返回标记值
	}
	return c.Store(seqSet, flags, nil).Close()
}

用一张表检查项目里的编号边界

排查“偶尔读到错误邮件”时，可以按这个顺序记录：请求发生在哪个邮箱、选中状态是否仍然有效、变量是 SeqSet 还是 UIDSet、集合生成后是否经历了 EXPUNGE 或同步、缓存里的 UIDValidity 是否与本次 SELECT 结果一致。通常比单纯重试请求更容易找到根因。

常见问题

UID 是不是全局唯一，可以只保存 UID 吗？

不是。UID 属于邮箱的命名空间，至少应与邮箱名绑定；当 UIDValidity 改变时，原来的 UID 缓存也不能继续直接使用。

SeqSet 和 UIDSet 都能传给 Fetch，为什么还要区分？

因为 API 的参数类型允许复用，不代表协议语义相同。前者描述消息序号，后者描述 UID；选择集合类型就是在选择服务器解释数字的方式。

搜索后直接调用 AllSeqNums 有问题吗？

如果只在当前列表快照里立即处理，可以使用序号结果；如果要异步处理、入队或跨连接恢复，应改用 UIDSearch 和 AllUIDs，并保存邮箱及 UIDValidity。

UID 一定不会变化吗？

不要把 UID 理解成脱离条件的永久全局 ID。它需要放在对应邮箱和 UIDValidity 下解释；一旦邮箱标识空间失效，旧缓存就应该重新搜索或清理。

Go go-imap 的编号问题，核心不是记住某个函数名，而是让数据结构表达生命周期：当前列表位置用 SeqSet，稳定定位用 UIDSet，跨请求保存时再加上邮箱与 UIDValidity。只要这三层边界在代码里保持一致，删信、重排和异步同步就不容易把一个数字误当成另一种身份。