Go go-smtp 怎样区分服务端声明扩展和客户端实际能力

Client.Extension(name) 查询的是当前 SMTP 会话中服务端公布的扩展名与参数，不是 go-smtp 客户端的功能注册表。判断能否实际使用一个扩展，还要查看当前依赖版本提供的方法或选项、当前连接状态与业务策略，并处理实际命令的返回错误。

官方项目地址：https://github.com/emersion/go-smtp

我在整理邮件接入代码时，会先把日志里的“支持”拆开：服务端说有 AUTH，不等于本地已经实现它公布的每个认证机制；有 STARTTLS，也不等于当前连接已经加密。本文用一个只读取能力、不发邮件的例子讲清判断顺序，不把假设场景说成真实故障经历。

先把能力拆成四层，避免一个布尔值包办所有判断

我采用的四层是：服务端声明、本地实现、会话条件与命令结果。服务端声明来自 EHLO 对话；本地实现来自项目实际锁定的客户端版本；会话条件包括TLS是否完成、认证身份与服务器策略；命令结果是本次操作的具体响应。前三者用于做选择，最后一层才能说明本次操作有没有被接受。

第一张结构图把“服务端视角”和“应用视角”分开：EHLO响应关联扩展表，Extension读取扩展表；本地API与会话条件共同关联命令结果，Extension查询结果也为选择操作提供信息。它是静态判断依据，不是通信时序。

读取声明：先保留问候错误，再看名称与参数

Extension会按需触发问候，其扩展名查询不区分大小写，返回值中第二项是服务端给出的参数字符串。一个存在但没有参数的扩展，也可能返回true与空字符串，不能只用参数非空判断存在。

另一个容易忽略的点是它没有error返回值：问候失败时可能同样得到false。对于新连接，我会先显式调用Hello并处理错误，再查询声明。Hello还用于选择本地问候名，必须在其他会触发问候的方法之前调用。遇到不支持EHLO而回退HELO的场景，不能把缺少ESMTP扩展表直接归因于网络故障。

对照本地接口：同名扩展不代表相同的操作入口

我不会从服务端返回的一串名称直接生成“本地全部可用”的列表。go-smtp同时包含客户端与服务端代码，项目概览中的扩展支持范围也不能替代对Client具体方法的检查。依赖升级时，应对照工程的实际版本文档和调用点，而不是只看仓库首页的一句话。

MailOptions.UTF8用于说明信封或邮件头中的UTF-8要求，不是把任意正文自动转换字符集；Size是请求中的大小参数，不负责替你测量整封邮件。一个字段能在类型中找到，也不代表所有对端都支持相应语义。

会话条件：STARTTLS与AUTH要分开记录

STARTTLS声明的意义是当前可协商TLS。TLS协商成功后，客户端需要根据新的会话重新取得能力信息，不能继续沿用升级前的AUTH列表。RFC 3207要求丢弃升级前获知的相应状态，因此我把能力快照视为当前连接阶段的数据，而不是这个主机永远不变的属性。

对于凭据认证，我会先明确服务器身份校验和TLS策略，再选择双方共同支持的机制。以PLAIN为例，本地需要一个相应的SASL客户端实现；SupportsAuth("PLAIN")只查服务端列出的机制，不会替你构造实现或校验密码。示例不读取、打印或发送任何凭据。

第二张图区分“服务声明”和“本地会话”：AUTH列表关联SupportsAuth，SupportsAuth与本地sasl.Client都关联Auth操作；TLS状态也是Auth操作的策略依据；SMTP响应关联本次Auth操作。这些关联不表示只要机制匹配就已获得授权。

一个只查询、不投递的能力快照函数

下面是可供业务调用的独立包函数，传入刚建立、尚未进行SMTP对话的net.Conn和本地问候名。它接管连接并负责关闭；连接建立和TLS握手的超时由调用方管理，函数中的CommandTimeout限制后续SMTP命令等待。代码需要Go 1.20或更高版本使用errors.Join。

package smtpinspect

import (
    "errors"
    "fmt"
    "net"
    "time"

    smtp "github.com/emersion/go-smtp"
)

type ExtensionInfo struct {
    Name string
    Advertised bool
    Params string
}
type Snapshot struct {
    Extensions []ExtensionInfo
    PlainAdvertised bool
    SizeKnown bool
    MaxSize int
    TLSHandshakeComplete bool
}

// Inspect 接管一个新建的、尚未进行SMTP对话的连接，结束时关闭。
// 可传已经完成握手的TLS连接；这里只观察，不认证、不发送邮件。
func Inspect(conn net.Conn, localName string) (s Snapshot, err error) {
    c := smtp.NewClient(conn)
    c.CommandTimeout = 5 * time.Second
    defer func() { err = errors.Join(err, c.Close()) }()

    // 显式保留问候失败，避免把失败误记成所有扩展均不支持。
    if err := c.Hello(localName); err != nil {
        return s, fmt.Errorf("SMTP问候失败: %w", err)
    }
    for _, name := range []string{"STARTTLS", "AUTH", "SMTPUTF8", "SIZE"} {
        ok, params := c.Extension(name)
        s.Extensions = append(s.Extensions, ExtensionInfo{
            Name: name, Advertised: ok, Params: params,
        })
    }
    // 这个布尔值只描述服务端公布的机制，不代表本地实现或登录成功。
    s.PlainAdvertised = c.SupportsAuth("PLAIN")
    s.MaxSize, s.SizeKnown = c.MaxMessageSize()
    if state, ok := c.TLSConnectionState(); ok {
        s.TLSHandshakeComplete = state.HandshakeComplete
    }
    return s, nil
}

如果传入的是普通TCP连接，这只是明文观察，不应随后拿它发送密码。需要安全会话时，可由调用方先建立并完成身份校验的TLS连接再传入；函数本身不执行STARTTLS。如果使用库的DialStartTLS入口，则由它管理升级与问候，后续不要再套用这个“接管原始连接”的函数或重复手动Hello。

函数故意把PlainAdvertised命名为“已声明”，而不是PlainUsable。MaxSize必须与SizeKnown一起使用：没有可用大小声明时不能把零值解释为明确无上限。TLSHandshakeComplete也只是状态记录，不能单凭这个字段替代对TLS配置和证书验证策略的判断。

本文未实际连接SMTP服务执行代码，因此没有预设某个服务一定返回哪些扩展。按逻辑推导，问候失败会返回带阶段说明的错误；问候成功后，Extensions保存四项声明快照，具体布尔值与参数取决于当前服务会话。函数既不调用Auth，也不调用Mail、Rcpt或Data，不产生邮件投递结果。

我会保留的流程与速查问答

我的推荐顺序是明确传输策略，建立连接并保留问候错误，记录当前声明，再核对本地调用与所需选项，最后依据具体命令错误处理异常。日志应带会话阶段和依赖版本，不要将完整认证交互或邮件内容写入调试日志。

Extension返回false一定是服务器不支持吗？不一定，要先排除问候失败；成功回退HELO时也不会获得ESMTP扩展表。不要只凭一个false就决定换服务器。

已经加密，STARTTLS却没有声明，算异常吗？不应仅据此判定异常。隐式TLS或升级后的会话已经处于TLS中，应该看实际连接状态与当前阶段，不能强求继续声明用于升级的入口。

能否只看SupportsAuth决定登录？不能，它只提供机制声明判断。本地实现、TLS策略、身份凭据与服务器响应仍须单独处理。

技术依据：官方Client API、官方客户端实现、MailOptions定义、STARTTLS规范、官方SASL PLAIN实现。能力分层、字段命名与快照函数为本文原创设计。