feat: add --json output support and update README

seamile · seamile · commit a66806548482 · 2026-01-17T02:47:29.000+08:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -31,6 +31,8 @@ libc = "0.2.180"
 ip2location = "0.6.0"
 dirs = "6.0.0"
 zip = "7.1.0"
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.149"
 
 [profile.release]
 opt-level = "z"
diff --git a/README.md b/README.md
@@ -9,6 +9,8 @@ PingX is a simple and practical network diagnostic tool designed to replace syst
 1. **Multi-Protocol**: ICMP, TCP, and HTTP probing.
 2. **Dual Stack**: Full support for IPv4, IPv6, and domain resolution.
 3. **Concurrency**: Probe multiple targets simultaneously.
+4. **GeoIP**: Retrieve geographical location (country, region, city, coordinates) for IP addresses.
+5. **JSON Output**: Export results to JSON for machine readability.
 
 ## Installation
 
@@ -87,6 +89,33 @@ Supports probing multiple targets simultaneously. Results are displayed interlea
 pingx 1.1.1.1 www.github.com
 ```
 
+### GeoIP Lookup
+
+Retrieve geographical information for IP addresses. The first run will guide you through downloading the IP2Location database.
+
+```shell
+# Lookup physical location
+pingx -g 1.1.1.1 8.8.8.8
+
+# Manually fetch/update database
+pingx --fetch-geo
+```
+
+### JSON Output
+
+Export results in structured JSON format. If one target, outputs an object; if multiple targets, outputs an array.
+
+```shell
+# Print JSON to stdout
+pingx 1.1.1.1 --json
+
+# Write JSON to file
+pingx 1.1.1.1 8.8.8.8 -c 5 --json result.json
+
+# JSON for GeoIP
+pingx -g 8.8.8.8 --json
+```
+
 ### Common Options
 
 - `-c <COUNT>`: Stop after sending count packets.
@@ -110,6 +139,8 @@ PingX 是一款简单实用的网络诊断工具，旨在替代系统的 `ping`
 1. **多协议支持**: 支持 ICMP、TCP 和 HTTP 协议探测。
 2. **双栈支持**: 完美支持 IPv4、IPv6 地址及域名解析。
 3. **并发探测**: 支持同时对多个目标发起探测。
+4. **GeoIP 信息**: 获取 IP 地址的物理地理位置（国家、地区、城市、经纬度）。
+5. **JSON 输出**: 支持将探测或定位结果以 JSON 格式输出，方便集成。
 
 ## 安装
 
@@ -189,6 +220,33 @@ pingx 可以并发对多个目标以不同协议进行检测。结果将交替
 pingx 1.1.1.1 www.github.com
 ```
 
+### GeoIP 位置查询
+
+获取 IP 地址的物理地理位置信息。第一次运行会引导你下载 IP2Location 数据库。
+
+```shell
+# 查询物理位置
+pingx -g 1.1.1.1 8.8.8.8
+
+# 手动更新/下载数据库
+pingx --fetch-geo
+```
+
+### JSON 格式输出
+
+将结果以结构化的 JSON 格式输出。单个目标输出对象 `{...}`，多个目标输出列表 `[{...}, ...]`。
+
+```shell
+# 打印 JSON 到屏幕
+pingx 1.1.1.1 --json
+
+# 保存 JSON 到文件
+pingx 1.1.1.1 8.8.8.8 -c 5 --json result.json
+
+# GeoIP 模式输出 JSON
+pingx -g 8.8.8.8 --json
+```
+
 ### 常用参数
 
 - `-c <COUNT>`: 发送数据包的数量。
diff --git a/src/cli.rs b/src/cli.rs
@@ -64,6 +64,10 @@ pub struct Cli {
     /// Fetch/Update the GeoIP database.
     #[arg(long = "fetch-geo", group = "mode")]
     pub fetch_geo: bool,
+
+    /// Output results in JSON format. Optional value specifies output file.
+    #[arg(long = "json", num_args = 0..=1, value_name = "FILE")]
+    pub json: Option<Option<String>>,
 }
 
 fn parse_duration(arg: &str) -> Result<Duration, std::num::ParseFloatError> {
diff --git a/src/geoip.rs b/src/geoip.rs
@@ -2,6 +2,7 @@ use anyhow::{Result, anyhow};
 use colored::Colorize;
 use ip2location::{DB, Record};
 use reqwest::Client;
+use serde::Serialize;
 use std::fs::File;
 use std::io::{self, Read, Seek, Write};
 use std::net::IpAddr;
@@ -236,6 +237,7 @@ impl GeoIpManager {
     }
 }
 
+#[derive(Serialize)]
 pub struct GeoRecord {
     pub ip: IpAddr,
     pub country: String,
diff --git a/src/main.rs b/src/main.rs
@@ -67,7 +67,30 @@ async fn main() {
         }
 
         if !records.is_empty() {
-            geoip::print_geo_table(&records);
+            if let Some(json_arg) = &args.json {
+                // JSON Output
+                use std::io::Write;
+                let json_output = if records.len() == 1 {
+                    serde_json::to_string_pretty(&records[0]).unwrap()
+                } else {
+                    serde_json::to_string_pretty(&records).unwrap()
+                };
+
+                if let Some(path) = json_arg {
+                    // Write to file
+                    if let Ok(mut file) = std::fs::File::create(path) {
+                        let _ = file.write_all(json_output.as_bytes());
+                    } else {
+                        eprintln!("pingx: Failed to write JSON to {}", path);
+                        std::process::exit(1);
+                    }
+                } else {
+                    // Write to stdout
+                    println!("{}", json_output);
+                }
+            } else {
+                geoip::print_geo_table(&records);
+            }
         }
 
         return;
diff --git a/src/session.rs b/src/session.rs
@@ -3,6 +3,7 @@ use crate::pinger::Pinger;
 use crate::utils::{IpVersion, resolve_host};
 use anyhow::Result;
 use colored::*;
+use serde::Serialize;
 use std::collections::HashMap;
 use std::time::Duration;
 use tokio::signal;
@@ -66,6 +67,24 @@ mod models {
 
 use std::sync::Arc;
 
+#[derive(Serialize)]
+pub struct JsonResult {
+    pub target: String,
+    pub protocol: String,
+    pub ip: String,
+    pub packet_size: usize,
+    pub ttl: u32,
+    pub sent: u64,
+    pub received: u64,
+    pub loss: f64,
+    pub time: f64,
+    pub min: f64,
+    pub avg: f64,
+    pub max: f64,
+    pub mdev: f64,
+    pub jitter: f64,
+}
+
 pub struct Session {
     cli: Cli,
 }
@@ -286,6 +305,100 @@ impl Session {
             p.stop().await.ok();
         }
 
+        // JSON Output Logic
+        if let Some(json_arg) = &self.cli.json {
+            let mut json_results = Vec::new();
+            
+            for target_host in targets {
+                if let Some(stats) = all_stats.get(target_host) {
+                    let protocol = target_protocols.get(target_host).unwrap_or(&crate::cli::Protocol::Icmp);
+                    let protocol_str = match protocol {
+                        crate::cli::Protocol::Icmp => "ICMP",
+                        crate::cli::Protocol::Tcp(_) => "TCP",
+                        crate::cli::Protocol::Http(_) => "HTTP",
+                    }.to_string();
+
+                    // Calculate stats
+                    let loss = if stats.transmitted > 0 {
+                        100.0 * (1.0 - stats.received as f64 / stats.transmitted as f64)
+                    } else {
+                        0.0
+                    };
+                    let total_time = stats.start_time.elapsed().as_secs_f64() * 1000.0;
+                    
+                    let (min, max, avg, mdev, jitter) = if stats.received > 0 {
+                        let min = stats.rtts.iter().min().unwrap().as_secs_f64() * 1000.0;
+                        let max = stats.rtts.iter().max().unwrap().as_secs_f64() * 1000.0;
+                        let avg = stats.rtts.iter().sum::<Duration>().as_secs_f64() * 1000.0 / stats.rtts.len() as f64;
+                        
+                        let avg_duration = Duration::from_secs_f64(avg / 1000.0);
+                        let sum_sq_diff: f64 = stats.rtts.iter()
+                            .map(|rtt| (rtt.as_secs_f64() - avg_duration.as_secs_f64()).abs())
+                            .sum();
+                        let mdev = sum_sq_diff / stats.rtts.len() as f64 * 1000.0;
+
+                        let jitter = if stats.rtts.len() > 1 {
+                             let sum_diff: f64 = stats.rtts.windows(2)
+                                .map(|w| (w[1].as_secs_f64() - w[0].as_secs_f64()).abs())
+                                .sum();
+                            sum_diff / (stats.rtts.len() - 1) as f64 * 1000.0
+                        } else {
+                            0.0
+                        };
+                        (
+                            (min * 1000.0).round() / 1000.0,
+                            (max * 1000.0).round() / 1000.0,
+                            (avg * 1000.0).round() / 1000.0,
+                            (mdev * 1000.0).round() / 1000.0,
+                            (jitter * 1000.0).round() / 1000.0,
+                        )
+                    } else {
+                        (0.0, 0.0, 0.0, 0.0, 0.0)
+                    };
+
+                    json_results.push(JsonResult {
+                        target: target_host.clone(),
+                        protocol: protocol_str,
+                        ip: stats._address.to_string(),
+                        packet_size: self.cli.size,
+                        ttl: self.cli.ttl,
+                        sent: stats.transmitted,
+                        received: stats.received,
+                        loss: (loss * 1000.0).round() / 1000.0, // Also round loss? Or keep precision? Instructions said "time values".
+                                                               // Let's stick to time values for strict compliance, 
+                                                               // but usually nice to format loss too.
+                                                               // Re-reading: "json 中的各项时间保留 3 位小数" -> time values only.
+                                                               // Loss is percentage. I will round time values.
+                        time: (total_time * 1000.0).round() / 1000.0, 
+                        min,
+                        avg,
+                        max,
+                        mdev,
+                        jitter,
+                    });
+                }
+            }
+
+            use std::io::Write;
+            let json_output = if json_results.len() == 1 {
+                serde_json::to_string_pretty(&json_results[0]).unwrap()
+            } else {
+                serde_json::to_string_pretty(&json_results).unwrap()
+            };
+
+            if let Some(path) = json_arg {
+                if let Ok(mut file) = std::fs::File::create(path) {
+                    let _ = file.write_all(json_output.as_bytes());
+                } else {
+                     eprintln!("pingx: Failed to write JSON to {}", path);
+                }
+            } else {
+                println!("{}", json_output);
+            }
+
+            return Ok(());
+        }
+
         // Collect table data and calculate global column widths
         let mut tables = Vec::new();
         let mut global_key_widths = [0usize; 3];
diff --git a/src/utils.rs b/src/utils.rs
@@ -424,6 +424,7 @@ mod tests {
             headers: vec![],
             geo: false,
             fetch_geo: false,
+            json: None,
         };
 
         // 1. Basic ICMP (Domain)

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ use anyhow::{Result, anyhow};`
`2`	`2`	`use colored::Colorize;`
`3`	`3`	`use ip2location::{DB, Record};`
`4`	`4`	`use reqwest::Client;`
	`5`	`+use serde::Serialize;`
`5`	`6`	`use std::fs::File;`
`6`	`7`	`use std::io::{self, Read, Seek, Write};`
`7`	`8`	`use std::net::IpAddr;`
`@@ -236,6 +237,7 @@ impl GeoIpManager {`
`236`	`237`	`}`
`237`	`238`	`}`
`238`	`239`
	`240`	`+#[derive(Serialize)]`
`239`	`241`	`pub struct GeoRecord {`
`240`	`242`	`pub ip: IpAddr,`
`241`	`243`	`pub country: String,`