Vue 3 应用运行在浏览器沙箱中，原生能力只覆盖 HTTP、WebSocket 和部分本地文件接口，无法直接向 AFP 服务端发起 TCP 548 端口上的文件共享请求。因此，工程化 AFP 的关键不是在前端重新实现协议栈，而是通过 BFF 网关把 AFP 的目录树、文件元数据和读写操作映射成浏览器可消费的 REST 资源与 WebSocket 事件。前端则负责请求队列、状态管理、断点续传和实时进度展示。这样既能沿用 AFP 服务端已有的权限体系，也能让 Vue 3 项目保持清晰的分层结构。
一、AFP 协议边界与 BFF 转换层设计
AFP 是 Apple Filing Protocol 的缩写，通常运行在 TCP 548 端口，依赖 DSI 会话层和 ASP 事务层完成卷挂载、目录枚举、文件读写与文件锁操作。虽然名字里带有归档二字，但 AFP 更准确的理解是苹果文件共享协议，和压缩归档格式是两个不同领域。Vue 3 运行在浏览器中，无法创建原始 TCP 548 连接，更没有权限处理 AFP 的二进制会话报文，所以前端不能也不需要直接实现 AFP 客户端。
正确的工程化边界是增加一个 BFF 服务。BFF 可以使用 Node.js、Go 或 Rust 实现，它负责与 AFP 服务端完成认证和协议交互，再把结果转换为 JSON 格式暴露给 Vue 3。目录浏览可以映射为 GET /api/afp/tree，文件下载映射为带 Range 头支持的 GET /api/afp/files，上传则映射为分片 PUT 接口。这样做还带来一个明显好处：AFP 账户密码和会话令牌不会出现在浏览器中。
// BFF 层：将 AFP 目录请求转换为前端可用的 JSON
import net from 'node:net';
const AFP_PORT = 548;
export async function listDirectory(host, volume, path, token) {
const socket = net.createConnection({ host, port: AFP_PORT });
// 省略 AFP DSI 握手与 ASP 会话建立细节
const command = buildAfpEnumerateCommand(volume, path, token);
socket.write(command);
const response = await readAfpResponse(socket);
socket.end();
return response.entries.map(entry => ({
name: entry.name,
type: entry.isDirectory ? 'directory' : 'file',
size: Number(entry.size),
modifiedAt: entry.modifiedAt,
path: `${path}/${entry.name}`,
}));
}
在实际项目中，BFF 层还需要处理 AFP 目录树的递归深度、隐藏文件过滤、路径规范化等问题。例如用户传入的路径可能包含 ..，BFF 必须做路径穿越校验，避免前端拼装出越权路径。另一个容易忽略的点是 AFP 返回的时间戳通常基于服务端时区或 Apple 时间格式，转换时最好统一成 ISO 8601 字符串，方便 Vue 3 组件格式化展示。
二、Vue 3 中的 AFP 资源模型与统一请求层
前端不应该在组件里零散地调用 fetch，而应通过一个统一的 AfpClient 类封装所有 AFP 资源操作。这样做的好处是：可以统一注入 baseUrl、超时时间、认证头以及错误处理策略。先把 AFP 目录项抽象成 AfpNode 类型，目录、文件和卷都用同一个结构表示，再通过 type 字段区分。
export type AfpNodeType = 'directory' | 'file' | 'volume';
export interface AfpNode {
path: string;
name: string;
type: AfpNodeType;
size: number;
modifiedAt: string;
children?: AfpNode[];
}
export interface AfpTransferTask {
id: string;
direction: 'upload' | 'download';
progress: number;
status: 'pending' | 'running' | 'paused' | 'completed' | 'failed';
error?: string;
chunks: number[];
}
export class AfpClient {
constructor(private baseUrl: string) {}
async listDirectory(path: string): Promise<AfpNode[]> {
const res = await fetch(`${this.baseUrl}/api/afp/tree?path=${encodeURIComponent(path)}`);
if (!res.ok) throw new AfpHttpError(res.status, await res.text());
return res.json();
}
}
在 Vue 3 组件中，可以结合响应式 ref 保存目录树，用 computed 过滤出文件与文件夹，再用 watch 监听当前路径变化自动重新加载。对于大目录，建议使用虚拟滚动组件渲染，而不是一次性把上千个节点全部插入 DOM。请求层还要支持 AbortController 取消，避免用户快速切换目录时旧请求覆盖新结果。
错误处理也不应该只停留在弹一条消息。可以根据 HTTP 状态码把错误分为认证失败、权限不足、文件不存在、网络超时四类。认证失败需要跳转登录页，权限不足提示申请目录授权，文件不存在刷新当前树，网络超时触发重试。统一错误模型能显著降低后续维护成本。
三、下载、上传与断点续传工程实现
AFP 文件通常体积不小，下载模块必须支持 Range 分片和断点续传。BFF 暴露下载接口时返回 Accept-Ranges: bytes，前端通过 AfpClient 的 downloadRange 方法按 4MB 分片拉取，再写入浏览器的 File System Access API 文件句柄。即使下载中途断网，已经写入本地文件的数据也不会丢失，恢复网络后可以从最后偏移量继续。
import { ref } from 'vue';
const CHUNK_SIZE = 1024 * 1024 * 4;
export function useAfpDownload(client: AfpClient) {
const progress = ref(0);
const status = ref<AfpTransferTask['status']>('pending');
async function download(filePath: string, targetHandle: FileSystemFileHandle) {
const meta = await client.getMeta(filePath);
const total = meta.size;
let offset = 0;
const writable = await targetHandle.createWritable();
while (offset < total) {
const end = Math.min(offset + CHUNK_SIZE - 1, total - 1);
const blob = await client.downloadRange(filePath, offset, end);
await writable.write({ type: 'write', position: offset, data: blob });
offset = end + 1;
progress.value = offset / total;
}
await writable.close();
status.value = 'completed';
}
return { progress, status, download };
}
上传侧的断点续传要更复杂一些。前端把文件按同样大小切分，先将文件哈希和总分片数发给 BFF 创建一个传输任务，再逐个上传分片。已成功上传的分片索引用 localStorage 或 IndexedDB 记录，任务中断后可以恢复到最近状态。BFF 收到全部分片后负责按顺序写入 AFP 目标文件，并做一次哈希校验，确保文件完整。
分片大小不是越大越好，4MB 在多数企业网络下表现稳定。如果文件小于 8MB，可以跳过断点续传直接走单请求上传，减少无谓的握手和状态记录。大文件上传时还要注意浏览器并发请求数限制，同时进行的分片请求最好控制在 3 到 6 个，避免占用过多带宽导致进度反而变慢。
四、实时进度推送与容错重试机制
轮询进度接口虽然实现简单，但在多任务并行时会迅速放大 BFF 的压力。更合适的方案是 WebSocket 推送。BFF 在 AFP 传输任务中每写入一组分片，就向对应频道广播 progress 和 bytesPerSecond。Vue 3 端通过 useTransferProgress 组合式函数订阅，收到消息后更新响应式状态，UI 用进度条和速度文本同步展示。
import { onMounted, onUnmounted, ref } from 'vue';
export function useTransferProgress(taskId: string) {
const progress = ref(0);
const speed = ref(0);
let socket: WebSocket | null = null;
function connect() {
socket = new WebSocket(`wss://${location.host}/api/afp/transfer-progress?taskId=${taskId}`);
socket.onmessage = (event) => {
const payload = JSON.parse(event.data);
progress.value = payload.progress;
speed.value = payload.bytesPerSecond;
};
}
onMounted(connect);
onUnmounted(() => socket?.close());
return { progress, speed };
}
网络波动时会遇到连接断开或短时 5xx。重试策略需要区分错误类型：认证错误和 403 权限错误不应该无限重试，而网络错误、超时和 502/503 可以指数退避。下面这个 retryWithBackoff 封装了常见逻辑，第一次重试等待 1 秒，之后依次翻倍，最多尝试 5 次。
export async function retryWithBackoff<T>(
fn: () => Promise<T>,
maxAttempts = 5,
baseDelay = 1000,
): Promise<T> {
let attempt = 0;
while (attempt < maxAttempts) {
try {
return await fn();
} catch (error) {
attempt += 1;
if (attempt >= maxAttempts) throw error;
const delay = baseDelay * 2 ** (attempt - 1);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw new Error('unreachable');
}
WebSocket 自身的重连也应该采用同样的退避思路，但不能直接复用 Promise 版本，因为连接需要持续保持。可以在 onclose 事件中累计重连次数，超过阈值后切换到轮询模式作为降级方案。这样即便某些企业网关拦截了 WebSocket 升级，文件传输仍能继续工作。
五、安全策略与部署注意事项
AFP 凭证绝不能暴露给浏览器。BFF 与 AFP 服务端之间可以使用独立服务账号，前端只持有短时效的 JWT。每次请求前由 BFF 校验 JWT 并映射到对应的 AFP 会话，JWT 过期后返回 401 让前端刷新。CORS 策略要精确到域名，不能为了方便直接放开 Access-Control-Allow-Origin: *。如果 AFP 目录涉及跨部门权限，建议在 BFF 中加入基于路径的 ACL 校验。
路径处理是另一处高风险点。AFP 共享目录在 Windows 服务端上可能写作 C:\Volumes\Shared，BFF 拼接路径时必须保留反斜杠语义，同时防止用户输入 ..\ 跳出共享根目录。所有来自前端的路径参数都应先经过 normalize，再与共享根目录做前缀比较，不通过则直接拒绝。
部署时可以把 BFF 与 Vue 3 构建产物放在同一域名下，用 Nginx 或 API 网关代理。生产环境建议开启 HTTPS 和 HTTP/2，文件下载接口可以借助服务端压缩减少传输量。日志中要避免记录 AFP 账户密码、完整文件内容或敏感文件名，只保留请求 ID、路径哈希和错误码，方便排查问题而不扩大隐私暴露面。