📚 课程目录第3章 JSON语法基础

3. JSON 语法基础：桶策略的编写规则与常见坑

写桶策略，说白了就是写一个 JSON 对象。JSON 看起来简单，但云上的策略编辑器可不会帮你纠错——写错一个引号，整条策略就废了。我刚开始接触 AWS 策略时，就曾因为少了一个双引号，排查了整整两个小时。嗯，从那以后我再也不敢小看 JSON 语法了。

3.1 JSON 的基本结构

桶策略的 JSON 遵循标准格式：最外层是一个花括号 {}，里面包含若干键值对。你想想看，每个键都必须用双引号括起来，值可以是字符串、数组、对象或布尔值。

一个典型的桶策略骨架是这样的：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::example-bucket/*"
    }
  ]
}

这里几个要点：

Version：固定值 "2012-10-17"，别写成其他版本号，我记得有同事试过写 "2012-10-18"，结果控制台直接报错。
Statement：数组，里面可以放多个策略条目。每个条目本身是一个对象。
Effect：只能是 "Allow" 或 "Deny"，注意大小写。
Principal：指定主体，可以是通配符 "*" 或一个 AWS 账户 ARN。
Action：字符串或字符串数组，比如 "s3:GetObject"。
Resource：桶 ARN 或对象 ARN，记得最后加 /* 表示所有对象。

个人习惯：我写策略时，会先写一个最小骨架（只允许一个操作），测试通过后再逐步添加。这样可以快速定位是语法错还是逻辑错。

3.2 引号规则——最容易翻车的地方

JSON 规定：所有键名必须用双引号包裹。值如果是字符串，也必须用双引号。单引号是不行的。我在项目中遇到过，把 'Allow' 写成单引号，结果 S3 直接返回 MalformedPolicy 错误。

再看一个典型错误：

// ❌ 错误：键用了单引号
{
  'Effect': 'Allow'
}

// ✅ 正确
{
  "Effect": "Allow"
}

另一个容易忽略的点：如果值里本身包含双引号，必须转义。比如你想在 Condition 中匹配一个包含双引号的字符串？嗯，这种情况很少见，但一旦遇到，不转义就等着报错吧。

场景	错误写法	正确写法
键名	`'Effect'` 或 `Effect`	`"Effect"`
字符串值	`'Allow'`	`"Allow"`
值中带双引号	`"he said "hello""`	`"he said \"hello\""`
数字（当字符串用）	`123`（会解析为数字，可能不符合预期）	`"123"`（强制字符串）

警告：某些在线 JSON 校验工具会允许单引号或未引用的键，但 AWS S3 的 JSON 解析器是严格模式。别依赖工具，直接按标准写。

3.3 转义字符——那些隐藏的陷阱

JSON 里的转义字符和大多数语言一样：反斜杠 \ 开头。但在桶策略中，最常用到的其实是转义双引号。举个例子，如果你要写一个拥有复杂前缀的条件，比如 "prefix": "user\"s files"。

再比如，在 Condition 的 StringLike 里，你可能会用到通配符 * 和 ?，它们本身不需要转义。但如果你要匹配一个真正的星号字符呢？那就得用 \*。不过说实话，这种场景我在生产环境几乎没见过，了解一下就行。

常见转义序列：

\" — 双引号
\\ — 反斜杠本身
\/ — 斜杠（非必须，但可读性更好）
\b, \f, \n, \r, \t — 控制字符，基本用不上

  我曾经踩过的坑：在 Resource 字段中写了 arn:aws:s3:::my-bucket/*，没问题。但有一次我把 /* 写成了 /*"（多了一个引号），结果整条策略无效。排查时发现是编辑器自动补全引号导致的。所以，**每次写完策略，我都手动检查最后一个字符是不是多余的引号**。

3.4 常见格式错误与避坑指南

写策略时，大部分错误来自以下几种：

多了一个逗号：对象最后一个键值对后面不能有逗号。很多新手喜欢在每行后面都加逗号，结果最后一项也加了，报错。
花括号不匹配：写了两个左花括号却只写一个右花括号。我习惯先从最内层往最外层写，每写一层就补全右括号。
数组元素之间丢了逗号：比如 ["a" "b"]，漏了逗号。
字符串值里出现了未转义的控制字符：比如换行符。JSON 不支持真正的换行，你必须在字符串里用 \n 来表示。

我推荐的一个小技巧：写完后，把整个 JSON 字符串复制到 JSONLint 或 jq 命令 里校验一下。不过 jq 对数字和字符串的区分很严格，比如 "123" 和 123 都能接受，但桶策略中某些字段（如 Version）必须是字符串，写成数字就会出错。

我个人的工作流：在本地用 VS Code 写 JSON，启用 JSON 语法校验插件。再在 AWS Console 里粘贴前，用 jq . 格式化一下，顺便验证语法。最后才贴到策略编辑器里保存。这招帮我拦住了至少 80% 的低级错误。

下面这张图帮你理清 JSON 语法的关键节点和常见错误种类：

看到这张图，你应该能快速定位自己的策略卡在哪个环节。从根 JSON 对象往下，引号、转义、键值对结构是三条主线。而最常见的错误都集中在右侧的“常见错误”区——多逗号、括号不匹配、单引号、值类型混淆。每次写完策略，对照这张图自查一遍，基本能过滤掉所有低级问题。