Skip to content

Commit

Permalink
docs: delete part content
Browse files Browse the repository at this point in the history
  • Loading branch information
chaoranz758 committed Aug 3, 2023
1 parent 4431d99 commit c7a91e7
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 65 deletions.
34 changes: 3 additions & 31 deletions content/en/docs/hertz/tutorials/basic-feature/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,6 @@ The following are requirements to enable Sonic:

Sonic automatically fallback to golang's `encoding/json` library when the above requirements have not been satisfied.

## Compatibility With `encoding/json`

Currently, Hertz uses the default configuration for Sonic (i.e.`sonic.ConfigDefault`), which behaves different from JSON `encoding/json`.
Specifically, by default, Sonic are configured to:

- disable html escape: Sonic will not escape HTML's special characters
- disable key-sort by default: Sonic will not sort json in lexicographical order

To find more about the compatibility with `encoding/json`, you may want to see [sonic#Compatibility](https://github.com/bytedance/sonic#compatibility).
You may change Sonic's behavior (e.g. behaving exactly the same way as `encoding/json`) by calling `ResetJSONMarshaler` for render.

```go
render.ResetJSONMarshaler(sonic.ConfigStd.Marshal)
```

## Bringing Your Own JSON Marshal Library

If Sonic does not meet your needs, you may provide your own implementation by calling `ResetJSONMarshal` for render and `ResetJSONUnmarshaler` for binding.
Expand All @@ -58,23 +43,10 @@ func main() {
Hertz supports conditional compilation to control the actual json library used, you can use `-tags stdjson` to choose to use the standard library.

```go
go build -tags stdjson .
go build -tags stdjson
```

## Common FAQs

### Error when using Sonic on M1

#### Build constraints exclude all Go files in xxx

Usually because the Go version or environment parameters do not meet Sonic requirements.

- Go version: go1.16 or above, recommend go1.17 or above. For the currently supported versions of Sonic, please see [Sonic#Requirement](https://github.com/bytedance/sonic#requirement).

- Go environment parameters: set GOARCH=**amd64**. Because Sonic already supports the binary translation software Rosetta, with Rosetta, the programs compiled under the x86 environment can be run on the M1.

#### Unable to Debug
## Sonic related issues

If you want to debug, you can set GOARCH=**arm64**. Because the Rosetta will cause the binary of Sonic to fail to debug.
If there are issues related to Sonic, please refer to Sonic [README](https://github.com/bytedance/sonic) or propose an issue.

Note that the performance of Sonic will be hurt, because Sonic will fallback to the standard library in this environment.
38 changes: 4 additions & 34 deletions content/zh/docs/hertz/tutorials/basic-feature/json.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ weight: 19
description: >
---

Hertz 默认集成并使用 [Sonic](https://github.com/bytedance/sonic) 用于序列化`ctx.JSON`接口,以及反序列化`binding`包中的请求。Sonic 是一款超高性能 golang json 库,详情参考 Sonic [README](https://github.com/bytedance/sonic)
Hertz 默认集成并使用 [Sonic](https://github.com/bytedance/sonic) 用于序列化 `ctx.JSON` 接口,以及反序列化 `binding` 包中的请求。Sonic 是一款超高性能 golang json 库,详情参考 Sonic [README](https://github.com/bytedance/sonic)

开启 Sonic 需要满足以下条件:

Expand All @@ -16,21 +16,6 @@ Hertz 默认集成并使用 [Sonic](https://github.com/bytedance/sonic) 用于

当上述条件不能满足时,Sonic 会自动 fallback 到 golang 的 encoding/json 库。

## 与 encoding/json 兼容性

当前 Hertz 使用 Sonic 的默认配置(即`sonic.ConfigDefault`),行为与标准库 encoding/json 有所差异,详见 [sonic#Compatibility](https://github.com/bytedance/sonic#compatibility)

具体来说,默认情况下,Sonic:

- 禁用 html escape:Sonic 不会转义 HTML 中的特殊字符
- 禁用 key-sort:Sonic 不会按照键对 JSON 排序

你可以通过调用 render 包中的`ResetJSONMarshaler`函数来修改 Sonic 的行为,比如保持和标准库兼容。

```go
render.ResetJSONMarshaler(sonic.ConfigStd.Marshal)
```

## 自定义 JSON Marshall 库

如果 Sonic 不能够满足您的需求,你可以使用以下方式自定义 json marshal 库的实现:
Expand All @@ -41,7 +26,6 @@ import (

"github.com/bytedance/go-tagexpr/v2/binding"
"github.com/cloudwego/hertz/pkg/app/server/render"

)
func main() {
// Render
Expand All @@ -57,23 +41,9 @@ func main() {
Hertz 支持条件编译来控制实际使用的 json 库,你可以通过 `-tags stdjson` 来选择使用标准库。

```go
go build -tags stdjson .
go build -tags stdjson
```

## 常见问题

### Mac M1 上使用 Sonic 报错

#### Build constraints exclude all Go files in xxx

一般是因为 Go 镜像版本或环境参数不符合 Sonic 要求。

- Go 版本:go1.16 或以上,推荐 go1.17 以上版本。Sonic 目前支持的版本见 [Sonic#Requirement](https://github.com/bytedance/sonic#requirement)

- Go 环境参数:设置 GOARCH=**amd64**。因为,Sonic 已经支持二进制翻译软件 Rosetta,借助 Rosetta,在 M1 上可运行 x86 环境下编译出来的程序。

#### 无法 Debug

如果想调试,可设置 GOARCH=**arm64**。因为 Rosetta 技术会导致 Sonic 的编译产物无法调试。
## Sonic 相关问题

注意,设置为 arm64 后将损失 Sonic 的高性能,因为 Sonic 内部在此环境下,会 fallback 到性能较差的标准库
若出现与 Sonic 相关的问题,可参考 Sonic [README](https://github.com/bytedance/sonic) 或提 issue 解决

0 comments on commit c7a91e7

Please sign in to comment.