Newtonsoft.Json (Json.NET) 常用方法汇总

命名空间：using Newtonsoft.Json;、using Newtonsoft.Json.Linq;

两套体系：

高级序列化：JsonConvert （实体 ↔ JSON字符串）

LINQ‑to‑JSON：JObject / JArray / JToken 动态操作JSON节点（你接口中使用的）

一、JsonConvert 实体与字符串互转

1. 实体对象 → JSON字符串

复制代码

// 对象序列化为JSON字符串
string jsonStr = JsonConvert.SerializeObject(obj);

// 格式化输出（带换行缩进，方便阅读）
string jsonPretty = JsonConvert.SerializeObject(obj, Formatting.Indented);

// 忽略空值、日期格式等配置
var setting = new JsonSerializerSettings
{
    Formatting = Formatting.Indented,
    NullValueHandling = NullValueHandling.Ignore,      // 忽略null属性不输出
    DateFormatString = "yyyy‑MM‑dd HH:mm:ss"          // 自定义日期格式
};
string json = JsonConvert.SerializeObject(model, setting);

2. JSON字符串 → C#实体对象

复制代码

// 反序列化到实体
var model = JsonConvert.DeserializeObject<MyModel>(jsonStr);

// 反序列化到动态JToken，不指定实体
var jtoken = JsonConvert.DeserializeObject(jsonStr);

二、LINQ‑to‑JSON （JToken/JObject/JArray，动态解析，你接口大量用到）

JToken：所有JSON节点的基类；

JObject：JSON对象 { "a":1 }

JArray：JSON数组 [1,2,3]

1. 从C#对象生成JObject / JArray

复制代码

// C#实体/字典 → JObject
JObject jObj = JObject.FromObject(myModel);

// List/数组 → JArray
JArray jArr = JArray.FromObject(listDto);

❗坑：List不能传给JObject.FromObject，会报 Object serialized to Array. JObject instance expected. ，必须用JArray.FromObject

2. 从JSON字符串解析

复制代码

// 字符串解析为JObject（要求是{}对象格式）
JObject jObj = JObject.Parse(jsonString);

// 字符串解析为JArray（要求是[]数组格式）
JArray jArr = JArray.Parse(jsonArrayString);

// 万能解析，不知道是对象还是数组，统一拿到JToken
JToken token = JToken.Parse(jsonStr);

3. 读取取值

复制代码

JObject jo = JObject.Parse("{\"name\":\"test\",\"value\":100}");

// 索引取值
string name = jo["name"]?.ToString();
int val = (int)jo["value"];

// 安全取值，防止key不存在报错
string safe = jo["NotExistKey"]?.Value<string>();

// 嵌套读取
string inner = jo["data"]["info"]["msg"]?.ToString();

// JArray遍历
JArray ja = JArray.Parse("[{\"v\":1},{\"v\":2}]");
foreach (JToken item in ja)
{
    int v = (int)item["v"];
}

4. 修改、新增字段

复制代码

JObject jo = new JObject();
jo["ExperimentRunStatus"] = JArray.FromObject(dtoList);
jo["Message"] = "ok";

// 删除key
jo.Remove("Message");

5. JToken转回字符串

复制代码

string jsonOut = jo.ToString();                     // 格式化带换行
string jsonCompact = jo.ToString(Formatting.None);   // 紧凑无换行（MQTT发送推荐）

6. JToken转为实体

复制代码

MyModel model = jo.ToObject<MyModel>();
List<MyDto> list = jArr.ToObject<List<MyDto>>();

三、特性（放在实体属性上）

复制代码

public class DemoModel
{
    // 序列化后的JSON字段名
    [JsonProperty("user_name")]
    public string UserName { get; set; }

    // 序列化时忽略该属性
    [JsonIgnore]
    public string TempField { get; set; }
}

四、常用JsonSerializerSettings配置（高频）

复制代码

var settings = new JsonSerializerSettings
{
    Formatting = Formatting.Indented,                // 缩进美化输出
    NullValueHandling = NullValueHandling.Ignore,     // 不序列化null的属性
    DateFormatHandling = DateFormatHandling.IsoDateFormat,
    DateFormatString = "yyyy‑MM‑dd HH:mm:ss",
    ReferenceLoopHandling = ReferenceLoopHandling.Ignore, // 解决循环引用报错
};

五、常见坑点整理（你项目遇到过）

JObject.FromObject(列表) → 报错Object serialized to Array，改用JArray.FromObject()
ValueTuple元组序列化 ：List<(int Value,string Name)> Newtonsoft会序列化为Item1,Item2，不能直接返回前端，需要中转DTO类。
JObject.Parse()传入数组字符串直接抛异常；数组字符串用JArray.Parse()
jo["key"] 不存在返回null，直接(int)jo["key"]会空引用；建议使用?.Value<T>()安全读取。
MQTT发送JSON报文，调用ToString(Formatting.None)生成紧凑JSON，减少传输字节。

快速记忆对照表

功能	方法
实体→JSON字符串	`JsonConvert.SerializeObject(obj)`
JSON字符串→实体	`JsonConvert.DeserializeObject<T>(str)`
对象转JObject	`JObject.FromObject(obj)`
List转JArray	`JArray.FromObject(list)`
JSON字符串解析对象	`JObject.Parse(str)`
JSON字符串解析数组	`JArray.Parse(str)`
JObject/JArray输出紧凑JSON	`.ToString(Formatting.None)`

如果你需要，我可以写一段示例：动态解析一段不确定结构的JSON，做安全读取。