第 7 章 网络请求

// 最基础的用法
const response = await fetch('https://api.github.com/repos/user/repo')
const data = await response.json()

// src/core/api-client.ts
type Middleware = (
  url: string,
  options: RequestInit,
  next: (url: string, options: RequestInit) => Promise<Response>,
) => Promise<Response>

// src/core/api-client.ts
const chain = this.middlewares.reduceRight(
  (next: (u: string, o: RequestInit) => Promise<Response>, middleware) => {
    return (u: string, o: RequestInit) => middleware(u, o, next)
  },
  (u: string, o: RequestInit) => fetch(u, o),
)

logging → retry → auth → fetch

// src/core/api-client.ts
static authMiddleware(getToken: () => string | undefined): Middleware {
  return (url, options, next) => {
    const token = getToken()
    if (token) {
      options.headers = {
        ...(options.headers as Record<string, string>),
        Authorization: `Bearer ${token}`,
      }
    }
    return next(url, options)
  }
}

// src/core/api-client.ts
static loggingMiddleware(): Middleware {
  return async (url, options, next) => {
    const method = (options.method ?? 'GET').toUpperCase()
    logger.debug(`→ ${method} ${url}`)
    const start = Date.now()
    const response = await next(url, options)
    const duration = Date.now() - start
    logger.debug(`← ${response.status} (${duration}ms)`)
    return response
  }
}

// src/core/api-client.ts — request 方法内部
const fetchOptions: RequestInit = {
  method,
  headers: { ...this.defaultHeaders, ...headers },
  signal: AbortSignal.timeout(timeout),  // 默认 30000ms
}

// src/core/api-client.ts
if (error instanceof DOMException && error.name === 'AbortError') {
  throw new NetworkError(`请求超时 (${timeout}ms)`, undefined, url)
}

// src/core/api-client.ts
static retryMiddleware(maxRetries = 3): Middleware {
  return async (url, options, next) => {
    let lastError: Error | undefined
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        const response = await next(url, options)
        // 5xx 才重试
        if (response.status >= 500 && attempt < maxRetries) {
          logger.debug(`请求失败 (${response.status})，第 ${attempt + 1} 次重试...`)
          await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
          continue
        }
        return response
      } catch (err) {
        lastError = err as Error
        if (attempt < maxRetries) {
          logger.debug(`请求异常，第 ${attempt + 1} 次重试...`)
          await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
        }
      }
    }
    throw lastError ?? new Error('请求失败')
  }
}

const delay = 1000 * Math.pow(2, attempt) + Math.random() * 500
await new Promise((r) => setTimeout(r, delay))

if (options.method === 'POST' && !options.headers?.['Idempotency-Key']) {
  return response  // POST 不重试，除非带了幂等键
}

import { ProxyAgent } from 'undici'
 
function getProxyAgent(): ProxyAgent | undefined {
  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy
    || process.env.HTTP_PROXY || process.env.http_proxy
 
  if (!proxy) return undefined
  return new ProxyAgent(proxy)
}

function shouldProxy(hostname: string): boolean {
  const noProxy = process.env.NO_PROXY || process.env.no_proxy
  if (!noProxy) return true
 
  const entries = noProxy.split(',').map(s => s.trim().toLowerCase())
  const host = hostname.toLowerCase()
 
  return !entries.some(entry => {
    if (entry === '*') return true
    if (entry.startsWith('.')) return host.endsWith(entry)
    return host === entry || host.endsWith('.' + entry)
  })
}

if (error.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
  throw new NetworkError(
    'TLS 证书验证失败（可能是自签名证书）',
    undefined,
    url,
  )
  // hint: 设置 NODE_EXTRA_CA_CERTS 环境变量指向 CA 证书
}

import dns from 'node:dns/promises'
 
async function isOnline(): Promise<boolean> {
  try {
    await dns.resolve('dns.google')
    return true
  } catch {
    return false
  }
}

async function handleNetworkFailure(error: Error, url: string): Promise<never> {
  const online = await isOnline()
  if (!online) {
    throw new NetworkError(
      '当前没有网络连接',
      undefined,
      url,
    )
  }
  // 有网但请求失败，可能是 DNS、防火墙、服务端问题
  throw new NetworkError(
    `请求失败: ${error.message}`,
    undefined,
    url,
  )
}

// src/core/api-client.ts
export class ApiClient {
  private baseUrl: string
  private defaultHeaders: Record<string, string>
  private middlewares: Middleware[] = []
 
  constructor(baseUrl: string, defaultHeaders: Record<string, string> = {}) {
    this.baseUrl = baseUrl.replace(/\/$/, '')
    this.defaultHeaders = {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      ...defaultHeaders,
    }
  }
}

// src/core/api-client.ts
async request<T = unknown>(
  endpoint: string,
  options: RequestOptions = {},
): Promise<ApiResponse<T>> {
  const url = endpoint.startsWith('http') ? endpoint : `${this.baseUrl}${endpoint}`
  const { method = 'GET', headers = {}, body, timeout = 30000 } = options
 
  const fetchOptions: RequestInit = {
    method,
    headers: { ...this.defaultHeaders, ...headers },
    signal: AbortSignal.timeout(timeout),
  }
 
  if (body !== undefined) {
    fetchOptions.body = JSON.stringify(body)
  }
 
  const chain = this.middlewares.reduceRight(
    (next: (u: string, o: RequestInit) => Promise<Response>, middleware) => {
      return (u: string, o: RequestInit) => middleware(u, o, next)
    },
    (u: string, o: RequestInit) => fetch(u, o),
  )
 
  try {
    const response = await chain(url, fetchOptions)
    if (!response.ok) {
      const errorBody = await response.text().catch(() => '')
      throw new NetworkError(
        `请求失败: ${response.status} ${response.statusText}${errorBody ? ` - ${errorBody}` : ''}`,
        response.status,
        url,
      )
    }
    const data = (await response.json()) as T
    return { status: response.status, headers: response.headers, data }
  } catch (error) {
    if (error instanceof NetworkError) throw error
    if (error instanceof DOMException && error.name === 'AbortError') {
      throw new NetworkError(`请求超时 (${timeout}ms)`, undefined, url)
    }
    throw new NetworkError(
      `网络错误: ${error instanceof Error ? error.message : '未知错误'}`,
      undefined,
      url,
    )
  }
}

// src/core/api-client.ts
async get<T>(endpoint: string, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>> {
  return this.request<T>(endpoint, { ...options, method: 'GET' })
}
 
async post<T>(endpoint: string, body?: unknown, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResponse<T>> {
  return this.request<T>(endpoint, { ...options, method: 'POST', body })
}

// src/core/api-client.ts
export function createGitHubClient(token?: string): ApiClient {
  const client = new ApiClient('https://api.github.com', {
    Accept: 'application/vnd.github+json',
    'X-GitHub-Api-Version': '2022-11-28',
  })
 
  client
    .use(ApiClient.loggingMiddleware())
    .use(ApiClient.retryMiddleware(2))
 
  if (token) {
    client.use(ApiClient.authMiddleware(() => token))
  }
 
  return client
}

// src/commands/deps.ts
const output = execSync(`npm view ${dep.name} version`, {
  encoding: 'utf-8',
  stdio: ['pipe', 'pipe', 'pipe'],
  timeout: 10000,
}).trim()

// 更高效的实现思路
const registryClient = new ApiClient('https://registry.npmjs.org')
  .use(ApiClient.retryMiddleware(1))
 
// 并行查询所有依赖的最新版本
const results = await Promise.allSettled(
  allDeps.map(async (dep) => {
    const { data } = await registryClient.get<{ 'dist-tags': { latest: string } }>(
      `/${dep.name}`
    )
    return {
      name: dep.name,
      current: dep.version,
      latest: data['dist-tags'].latest,
    }
  })
)

async function parallelLimit<T>(
  tasks: (() => Promise<T>)[],
  limit: number,
): Promise<PromiseSettledResult<T>[]> {
  const results: PromiseSettledResult<T>[] = []
  let index = 0
 
  async function runNext(): Promise<void> {
    while (index < tasks.length) {
      const i = index++
      try {
        const value = await tasks[i]()
        results[i] = { status: 'fulfilled', value }
      } catch (reason) {
        results[i] = { status: 'rejected', reason }
      }
    }
  }
 
  await Promise.all(Array.from({ length: limit }, () => runNext()))
  return results
}
 
// 最多 5 个并发请求
const results = await parallelLimit(
  allDeps.map((dep) => () => registryClient.get(`/${dep.name}`)),
  5,
)

Error: fetch failed

✖ 网络请求失败: 请求超时 (30000ms)
  请求地址: https://api.github.com/repos/user/repo
  提示: 检查网络连接，或使用 --timeout 增加超时时间

// src/core/error.ts
} else if (error instanceof NetworkError) {
  console.error(chalk.red('✖'), `网络请求失败: ${error.message}`)
  if (error.url) {
    console.error(chalk.gray('  请求地址:'), error.url)
  }
  if (error.statusCode) {
    console.error(chalk.gray('  状态码:'), error.statusCode)
  }
  process.exit(ExitCode.GENERAL_ERROR)
}

┌─────────────────────────────────────────────────┐
│                    CLI 入口                       │
│              src/cli.ts (Commander)               │
└──────────────┬────────────────────────────────────┘
               │ 注册命令
  ┌────────────┼────────────┬──────────────┐
  │            │            │              │
  ▼            ▼            ▼              ▼
┌──────┐  ┌──────┐   ┌──────────┐   ┌──────────┐
│ init │  │ scan │   │  config  │   │   auth   │
│(ch3) │  │(ch4) │   │  (ch5)   │   │  (ch6)   │
└──┬───┘  └──┬───┘   └────┬─────┘   └────┬─────┘
   │         │            │               │
   ▼         ▼            ▼               ▼
┌──────────────────────────────────────────────────┐
│                   核心模块层                       │
│  logger(ch4) │ error(ch4) │ config(ch5) │ auth(ch6) │
└──────────────────────────┬───────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────┐
│                   基础设施层                       │
│     api-client(ch7)  │  git utils  │  format     │
└──────────────────────────────────────────────────┘