脚本如何记录接口调用日志

wen 实用脚本 2026-06-30 24

从零搭建高效日志系统的完整指南

📖 目录导读

为什么需要记录接口日志？ —— 业务与技术的双重驱动力
脚本日志的核心要素 —— 记录什么、怎么记、存哪里
主流脚本语言日志方案
- Python：logging + 面向接口封装
- Shell：简单高效的文本处理
- Node.js：winston 与 pino 实战
日志存储与性能优化 —— 文件、数据库与集中式平台的取舍
实战案例：一个完整的企业级接口日志记录脚本
常见问题与解决方案 —— 日志丢失、性能瓶颈、安全合规
搜索引擎FAQ —— 用户最关心的5个问题

为什么需要记录接口日志？

业务视角

排查线上问题：当用户反馈“支付失败”，日志是唯一能还原现场的证据
监控接口质量：记录响应时间、错误率，为SLA提供数据支撑
安全审计：追踪异常请求，抵御恶意攻击（如频繁调用、SQL注入探测）

技术视角

调试与开发：测试环境缺少日志等于“盲人摸象”
性能分析：通过日志定位慢查询、高延迟接口
链路追踪：微服务架构下，日志是串联分布式调用的粘合剂

❓ 问：记录日志会不会拖慢接口性能？
答：会，但通过异步写入、缓冲队列、日志分级（仅ERROR级别写入磁盘）可将影响控制在5%以内，现代日志库如 pino（Node.js）性能接近原生console，建议优先选用。

脚本日志的核心要素

一个优秀的接口调用日志应包含以下字段：

字段	示例值	作用
请求ID	`req-20231015-abc123`	关联单次请求的全生命周期
时间戳	`2023-10-15T14:30:00.123Z`	精确到毫秒，用于排序分析
请求方法	`POST`	区分操作类型
请求路径	`/api/v1/order/create`	识别被调接口
请求参数	`{"userId": 1001}`	参数验证与问题复现
响应码	`200` 或 `500`	快速判断成功/失败
耗时	`234ms`	性能指标
客户端IP	`168.1.1`	来源追踪与速率限制

核心原则：应记尽记，但避免记录敏感信息（密码、Token、银行卡号）。

主流脚本语言日志方案

1 Python：使用 `logging` 模块封装接口日志

import logging
import time
import uuid
# 配置日志器
logger = logging.getLogger("api_logger")
handler = logging.FileHandler("api.log")
formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)
def log_api_call(method, path, params, response, status_code, duration):
    log_entry = {
        "request_id": str(uuid.uuid4()),
        "method": method,
        "path": path,
        "params": params,
        "status": status_code,
        "duration": f"{duration:.2f}ms"
    }
    logger.info(str(log_entry))
# 使用示例
start = time.time()
resp = {"orderId": 12345}  # 假设的响应
log_api_call("POST", "/api/order", {"userId": 1}, resp, 200, (time.time()-start)*1000)

❓ 问：为什么不用 print 直接输出？
答：logging 支持分级、滚动文件、异步写入、日志格式化等企业级能力，print 无法控制输出目标，且在高并发下会严重拖慢性能。

2 Shell脚本：轻量级日志方案

对于Linux运维脚本,使用 logger 命令或重定向：

#!/bin/bash
API_URL="https://www.example.com/api/check"
LOG_FILE="/var/log/api_check.log"
log() {
    echo "$(date '+%Y-%m-%d %H:%M:%S') | $1 | $2" >> $LOG_FILE
}
# 调用接口
start_time=$(date +%s%N)
response=$(curl -s -w "%{http_code}" -o /dev/null $API_URL)
end_time=$(date +%s%N)
duration=$(( (end_time - start_time) / 1000000 ))
log "INFO" "GET /api/check | HTTP $response | ${duration}ms"

优化建议：使用 logrotate 配置日志轮转，避免单个日志文件过大。

3 Node.js：Winston vs Pino 选型

// 使用 winston（功能全面）
const winston = require('winston');
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'api.log' })
  ]
});
// 日志中间件（Express示例）
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    logger.info({
      method: req.method,
      path: req.path,
      status: res.statusCode,
      duration: Date.now() - start,
      ip: req.ip
    });
  });
  next();
});

Pino 性能对比：在10万次/秒的写入场景下，Pino 比 Winston 快40%，但 Winston 的生态系统更成熟，建议生产选 Pino，开发调试选 Winston。

日志存储与性能优化

存储方式	优点	缺点	适用场景
本地文件	简单、无需外部依赖	扩容难、查询慢	单机、测试环境
数据库（MySQL/PostgreSQL）	结构查询、支持索引	写入I/O瓶颈	低频调用（<1000次/秒）
Elasticsearch + Logstash	全文搜索、可扩展	运维成本高、资源消耗大	大型生产集群
云日志服务（AWS CloudWatch）	免运维、自动扩缩	依赖云厂商、成本可控	云原生应用

性能优化口诀：

异步写：日志不阻塞主流程
缓冲队列：批量写入减少IO次数
日志分级：INFO级别可异步丢弃，ERROR必保
采样降级：高并发时按1/10采样

❓ 问：日志文件越来越大怎么办？
答：配置 logrotate（Linux）或使用日志库的 RotatingFileHandler（Python），按大小（如100MB）或时间（每天）切割，保留最近7天或1GB。

实战案例：一个完整的企业级接口日志记录脚本

以下以Python为例,整合了错误重试、性能监控、敏感信息脱敏：

import json
import time
import hashlib
import requests
from logging.handlers import RotatingFileHandler
# 脱敏函数：隐藏敏感参数
def mask_sensitive(data, keys=['password', 'token', 'idCard']):
    if isinstance(data, dict):
        return {k: ('***' if k in keys else mask_sensitive(v)) for k, v in data.items()}
    return data
# 配置日志（带滚动）
handler = RotatingFileHandler("api_trace.log", maxBytes=10*1024*1024, backupCount=5)
formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
handler.setFormatter(formatter)
logger = logging.getLogger(__name__)
logger.addHandler(handler)
def safe_api_call(method, url, headers=None, body=None, timeout=30):
    request_id = hashlib.md5(str(time.time() + random()).encode()).hexdigest()[:12]
    start = time.time()
    try:
        response = requests.request(method, url, headers=headers, json=body, timeout=timeout)
        status = response.status_code
        resp_body = response.json() if response.text else {}
    except Exception as e:
        status = 0  # 网络错误
        resp_body = {"error": str(e)}
        logger.error(f"REQ_ID={request_id} | 调用失败 | {e}")
    duration_ms = round((time.time() - start) * 1000, 2)
    # 记录日志（脱敏后）
    log_entry = {
        "request_id": request_id,
        "method": method,
        "url": url,
        "request_body": mask_sensitive(body or {}),
        "response": mask_sensitive(resp_body),
        "status": status,
        "duration_ms": duration_ms
    }
    logger.info(json.dumps(log_entry))
    return response if status == 200 else None
# 使用示例
safe_api_call("POST", "https://www.example.com/api/login", 
              body={"username": "admin", "password": "secret", "token": "xxx"})

运行结果示例（脱敏后）：

2025-10-15 14:30:01 | INFO | {"request_id": "a1b2c3d4e5f6", "method": "POST", "url": "https://www.example.com/api/login", "request_body": {"username": "admin", "password": "***", "token": "***"}, "response": {"user": "admin", "token": "***"}, "status": 200, "duration_ms": 234}

常见问题与解决方案

问题	原因	解决
日志丢失	进程崩溃、磁盘满、异步写入未刷新	增加 `flush()` 调用；监控磁盘空间；使用可靠的日志后端（如ELK）
性能瓶颈	同步日志写入导致接口超时	改用异步日志库（如Python的`QueueHandler`）；日志采样
敏感信息泄露	记录完整请求参数	实现脱敏中间件，覆盖密码、Token、身份证号等
日志时间不统一	服务器时区差异	统一使用UTC时间，前端显示时转换为本地时间
磁盘空间爆炸	未配置日志轮转	使用 `logrotate` 或 `RotatingFileHandler`；设置最大保留天数

搜索引擎FAQ：用户最关心的5个问题

Q1: 脚本接口日志应该记录在文件还是数据库？
A: 初期用文件（快速部署），日请求量超过10万次建议迁移到数据库（如Elasticsearch）或云日志服务。

Q2: 如何不记录错误日志？
A: 在日志配置中设置 level=logging.ERROR 则只记录错误级别，或在中段间中过滤非ERROR请求。

Q3: 日志记录是否会影响接口吞吐量？
A: 采用异步写入（如Python的 logging.handlers.QueueHandler）+ 缓冲池，可降低影响至1ms/条以内。

Q4: 如何从日志中分析接口调用趋势？
A: 结合 grep 按时间筛选，或导入到时序数据库（如InfluxDB）做可视化。

Q5: 如何在微服务间关联日志？
A: 使用全局请求ID，通过HTTP头（如 X-Request-ID）传递，在调用链中透传。

推荐工具：OpenTelemetry 自动注入分布式请求ID，EFK（Elasticsearch + Filebeat + Kibana）实现集中化日志分析。

记录接口调用日志不仅是“加几行打印”，而是从日志设计 -> 存储选型 -> 性能优化 -> 安全合规的系统工程，对于中小团队，建议从 Python logging + 文件滚动 起步；当流量增长后，逐步迁移至 ELK 或 云日志服务，始终记住：日志的真正价值不在于记录，而在于被查询和分析。