api-grammar.html


<!DOCTYPE HTML>
<html lang="zh-hans" >
    <head>
        <meta charset="UTF-8">
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <title>api语法介绍 · go-zero使用文档</title>
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="description" content="">
        <meta name="generator" content="GitBook 3.2.3">
        <meta name="author" content="松妹子">
        
        
    <link rel="stylesheet" href="gitbook/style.css">

    
                <link rel="stylesheet" href="gitbook/gitbook-plugin-back-to-top-button/plugin.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-chapter-fold/chapter-fold.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-code/plugin.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-search-pro/search.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-splitter/splitter.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-tbfed-pagefooter/footer.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-flexible-alerts/style.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-page-toc-button/plugin.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-pageview-count/plugin.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-prism/prism-tomorrow.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
                
            
                <link rel="stylesheet" href="gitbook/gitbook-plugin-theme-comscore/test.css">
                
            
    <meta name="HandheldFriendly" content="true"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black">
    <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
    <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">

    
    <link rel="next" href="api-dir.html" />
    
    
    <link rel="prev" href="go-zero-features.html" />
    

    </head>
    <body>
        
<div class="book">
    <div class="book-summary">
        
            
<div id="book-search-input" role="search">
    <input type="text" placeholder="输入并搜索" />
</div>

            
                <nav role="navigation">
                

<ul class="summary">
    
    
        <li class="chapter " data-level="1.1" data-path="./">
            
                <a href="./">
            
                    
                    简介
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.2" data-path="about-us.html">
            
                <a href="about-us.html">
            
                    
                    关于我们
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.3" data-path="join-us.html">
            
                <a href="join-us.html">
            
                    
                    加入我们
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.4" data-path="concept-introduction.html">
            
                <a href="concept-introduction.html">
            
                    
                    概念介绍
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5" data-path="quick-start.html">
            
                <a href="quick-start.html">
            
                    
                    快速开发
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.5.1" data-path="monolithic-service.html">
            
                <a href="monolithic-service.html">
            
                    
                    单体服务
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.5.2" data-path="micro-service.html">
            
                <a href="micro-service.html">
            
                    
                    微服务
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.6" data-path="framework-design.html">
            
                <a href="framework-design.html">
            
                    
                    框架设计
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.6.1" data-path="go-zero-design.html">
            
                <a href="go-zero-design.html">
            
                    
                    go-zero设计理念
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.2" data-path="go-zero-features.html">
            
                <a href="go-zero-features.html">
            
                    
                    go-zero特点
            
                </a>
            

        </li>
    
        <li class="chapter active" data-level="1.6.3" data-path="api-grammar.html">
            
                <a href="api-grammar.html">
            
                    
                    api语法介绍
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.4" data-path="api-dir.html">
            
                <a href="api-dir.html">
            
                    
                    api目录结构
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.6.5" data-path="rpc-dir.html">
            
                <a href="rpc-dir.html">
            
                    
                    rpc目录结构
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7" data-path="project-dev.html">
            
                <a href="project-dev.html">
            
                    
                    项目开发
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.1" data-path="prepare.html">
            
                <a href="prepare.html">
            
                    
                    准备工作
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.1.1" data-path="golang-install.html">
            
                <a href="golang-install.html">
            
                    
                    golang安装
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.1.2" data-path="gomod-config.html">
            
                <a href="gomod-config.html">
            
                    
                    go modudle配置
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.1.3" data-path="goctl-install.html">
            
                <a href="goctl-install.html">
            
                    
                    goctl安装
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.1.4" data-path="protoc-install.html">
            
                <a href="protoc-install.html">
            
                    
                    protoc&protoc-gen-go安装
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.1.5" data-path="prepare-other.html">
            
                <a href="prepare-other.html">
            
                    
                    其他
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7.2" data-path="dev-specification.html">
            
                <a href="dev-specification.html">
            
                    
                    开发规范
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.2.1" data-path="naming-spec.html">
            
                <a href="naming-spec.html">
            
                    
                    命名规范
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.2.2" data-path="route-naming-spec.html">
            
                <a href="route-naming-spec.html">
            
                    
                    路由规范
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.2.3" data-path="coding-spec.html">
            
                <a href="coding-spec.html">
            
                    
                    编码规范
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7.3" data-path="dev-flow.html">
            
                <a href="dev-flow.html">
            
                    
                    开发流程
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.4" data-path="config-introduction.html">
            
                <a href="config-introduction.html">
            
                    
                    配置介绍
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.4.1" data-path="api-config.html">
            
                <a href="api-config.html">
            
                    
                    api配置
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.4.2" data-path="rpc-config.html">
            
                <a href="rpc-config.html">
            
                    
                    rpc配置
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7.5" data-path="business-dev.html">
            
                <a href="business-dev.html">
            
                    
                    业务开发
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.7.5.1" data-path="service-design.html">
            
                <a href="service-design.html">
            
                    
                    目录拆分
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.2" data-path="model-gen.html">
            
                <a href="model-gen.html">
            
                    
                    model生成
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.3" data-path="api-coding.html">
            
                <a href="api-coding.html">
            
                    
                    api文件编写
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.4" data-path="business-coding.html">
            
                <a href="business-coding.html">
            
                    
                    业务编码
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.5" data-path="jwt.html">
            
                <a href="jwt.html">
            
                    
                    jwt鉴权
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.6" data-path="middleware.html">
            
                <a href="middleware.html">
            
                    
                    中间件使用
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.7" data-path="rpc-call.html">
            
                <a href="rpc-call.html">
            
                    
                    rpc服务编写与调用
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.5.8" data-path="error-handle.html">
            
                <a href="error-handle.html">
            
                    
                    错误处理
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.7.6" data-path="ci-cd.html">
            
                <a href="ci-cd.html">
            
                    
                    CI/CD
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.7" data-path="service-deployment.html">
            
                <a href="service-deployment.html">
            
                    
                    服务部署
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.8" data-path="log-collection.html">
            
                <a href="log-collection.html">
            
                    
                    日志收集
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.9" data-path="trace.html">
            
                <a href="trace.html">
            
                    
                    链路追踪
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.7.10" data-path="service-monitor.html">
            
                <a href="service-monitor.html">
            
                    
                    服务监控
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.8" data-path="goctl.html">
            
                <a href="goctl.html">
            
                    
                    Goctl
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.8.1" data-path="goctl-commands.html">
            
                <a href="goctl-commands.html">
            
                    
                    命令大全
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.8.2" data-path="goctl-api.html">
            
                <a href="goctl-api.html">
            
                    
                    api命令
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.8.3" data-path="goctl-rpc.html">
            
                <a href="goctl-rpc.html">
            
                    
                    rpc命令
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.8.4" data-path="goctl-model.html">
            
                <a href="goctl-model.html">
            
                    
                    model命令
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.8.5" data-path="goctl-plugin.html">
            
                <a href="goctl-plugin.html">
            
                    
                    plugin命令
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.8.6" data-path="goctl-other.html">
            
                <a href="goctl-other.html">
            
                    
                    其他命令
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.9" data-path="component-center.html">
            
                <a href="component-center.html">
            
                    
                    组件中心
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.9.1" data-path="logx.html">
            
                <a href="logx.html">
            
                    
                    logx
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.2" data-path="bloom.html">
            
                <a href="bloom.html">
            
                    
                    bloom
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.3" data-path="executors.html">
            
                <a href="executors.html">
            
                    
                    executors
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.4" data-path="fx.html">
            
                <a href="fx.html">
            
                    
                    fx
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.5" data-path="mysql.html">
            
                <a href="mysql.html">
            
                    
                    mysql
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.6" data-path="redis-lock.html">
            
                <a href="redis-lock.html">
            
                    
                    redis-lock
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.7" data-path="periodlimit.html">
            
                <a href="periodlimit.html">
            
                    
                    periodlimit
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.8" data-path="tokenlimit.html">
            
                <a href="tokenlimit.html">
            
                    
                    tokenlimit
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.9.9" data-path="timing-wheel.html">
            
                <a href="timing-wheel.html">
            
                    
                    TimingWheel
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.10" data-path="tool-center.html">
            
                <a href="tool-center.html">
            
                    
                    工具中心
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.10.1" data-path="intellij.html">
            
                <a href="intellij.html">
            
                    
                    intellij插件
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.10.2" data-path="vscode.html">
            
                <a href="vscode.html">
            
                    
                    vscode插件
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.11" data-path="plugin-center.html">
            
                <a href="plugin-center.html">
            
                    
                    插件中心
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.12" data-path="learning-resource.html">
            
                <a href="learning-resource.html">
            
                    
                    学习资源
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.12.1" data-path="wechat.html">
            
                <a href="wechat.html">
            
                    
                    公众号
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.12.2" data-path="goreading.html">
            
                <a href="goreading.html">
            
                    
                    Go夜读
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.12.3" data-path="gotalk.html">
            
                <a href="gotalk.html">
            
                    
                    Go开源说
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.13" data-path="practise.html">
            
                <a href="practise.html">
            
                    
                    开发实践
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.13.1" data-path="redis-cache.html">
            
                <a href="redis-cache.html">
            
                    
                    go-zero缓存设计之持久层缓存
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.13.2" data-path="buiness-cache.html">
            
                <a href="buiness-cache.html">
            
                    
                    go-zero缓存设计之业务层缓存
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.13.3" data-path="go-queue.html">
            
                <a href="go-queue.html">
            
                    
                    go-zero分布式定时任务
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.13.4" data-path="datacenter.html">
            
                <a href="datacenter.html">
            
                    
                    我是如何用go-zero 实现一个中台系统
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.13.5" data-path="stream.html">
            
                <a href="stream.html">
            
                    
                    流数据处理利器
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.13.6" data-path="online-exchange.html">
            
                <a href="online-exchange.html">
            
                    
                    10月3日线上交流问题汇总
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.14" data-path="dev-log.html">
            
                <a href="dev-log.html">
            
                    
                    开发日志
            
                </a>
            

            <ul class="articles">
                
    
        <li class="chapter " data-level="1.14.1" data-path="goctl-log.html">
            
                <a href="goctl-log.html">
            
                    
                    goctl开发日志
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.14.2" data-path="intellij-log.html">
            
                <a href="intellij-log.html">
            
                    
                    intellij开发日志
            
                </a>
            

        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="1.15" data-path="contributor.html">
            
                <a href="contributor.html">
            
                    
                    贡献人员
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.16" data-path="doc-contibute.html">
            
                <a href="doc-contibute.html">
            
                    
                    文档贡献
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.17" data-path="error.html">
            
                <a href="error.html">
            
                    
                    常见错误处理
            
                </a>
            

        </li>
    
        <li class="chapter " data-level="1.18" data-path="source.html">
            
                <a href="source.html">
            
                    
                    相关源码
            
                </a>
            

        </li>
    

    <li class="divider"></li>

    <li>
        <a href="https://www.gitbook.com" target="blank" class="gitbook-link">
            本书使用 GitBook 发布
        </a>
    </li>
</ul>


                </nav>
            
        
    </div>

    <div class="book-body">
        
            <div class="body-inner">
                
                    
<div class="book-header" role="navigation">
    

    <!-- Title -->
    <h1>
        <i class="fa fa-circle-o-notch fa-spin"></i>
        <a href="." >api语法介绍</a>
    </h1>
</div>


                    <div class="page-wrapper" tabindex="-1" role="main">
                        <div class="page-inner">
                            
<div id="book-search-results">
    <div class="search-noresults">
    
                                <section class="normal markdown-section">
                                
                                <h1 id="api&#x8BED;&#x6CD5;&#x4ECB;&#x7ECD;">api&#x8BED;&#x6CD5;&#x4ECB;&#x7ECD;</h1>
<h2 id="api&#x793A;&#x4F8B;">api&#x793A;&#x4F8B;</h2>
<pre class="language-"><code class="lang-go"><span class="token comment">/**
 * api&#x8BED;&#x6CD5;&#x793A;&#x4F8B;&#x53CA;&#x8BED;&#x6CD5;&#x8BF4;&#x660E;
 */</span>

<span class="token comment">// api&#x8BED;&#x6CD5;&#x7248;&#x672C;</span>
syntax <span class="token operator">=</span> <span class="token string">&quot;v1&quot;</span>

<span class="token comment">// import literal</span>
<span class="token keyword">import</span> <span class="token string">&quot;foo.api&quot;</span>

<span class="token comment">// import group</span>
<span class="token keyword">import</span> <span class="token punctuation">(</span>
    <span class="token string">&quot;bar.api&quot;</span>
    <span class="token string">&quot;foo/bar.api&quot;</span>
<span class="token punctuation">)</span>
<span class="token function">info</span><span class="token punctuation">(</span>
    author<span class="token punctuation">:</span> <span class="token string">&quot;songmeizi&quot;</span>
    date<span class="token punctuation">:</span>   <span class="token string">&quot;2020-01-08&quot;</span>
    desc<span class="token punctuation">:</span>   <span class="token string">&quot;api&#x8BED;&#x6CD5;&#x793A;&#x4F8B;&#x53CA;&#x8BED;&#x6CD5;&#x8BF4;&#x660E;&quot;</span>
<span class="token punctuation">)</span>

<span class="token comment">// type literal</span>

<span class="token keyword">type</span> Foo<span class="token punctuation">{</span>
    Foo <span class="token builtin">int</span> <span class="token string">`json:&quot;foo&quot;`</span>
<span class="token punctuation">}</span>

<span class="token comment">// type group</span>

<span class="token keyword">type</span><span class="token punctuation">(</span>
    Bar<span class="token punctuation">{</span>
        Bar <span class="token builtin">int</span> <span class="token string">`json:&quot;bar&quot;`</span>
    <span class="token punctuation">}</span>
<span class="token punctuation">)</span>

<span class="token comment">// service block</span>
@<span class="token function">server</span><span class="token punctuation">(</span>
    jwt<span class="token punctuation">:</span>   Auth
    group<span class="token punctuation">:</span> foo
<span class="token punctuation">)</span>
service foo<span class="token operator">-</span>api<span class="token punctuation">{</span>
    @doc <span class="token string">&quot;foo&quot;</span>
    @handler foo
    post <span class="token operator">/</span>foo <span class="token punctuation">(</span>Foo<span class="token punctuation">)</span> returns <span class="token punctuation">(</span>Bar<span class="token punctuation">)</span>
<span class="token punctuation">}</span>
</code></pre>
<h2 id="api&#x8BED;&#x6CD5;&#x7ED3;&#x6784;">api&#x8BED;&#x6CD5;&#x7ED3;&#x6784;</h2>
<ul>
<li>syntax&#x8BED;&#x6CD5;&#x58F0;&#x660E;</li>
<li>import&#x8BED;&#x6CD5;&#x5757;</li>
<li>info&#x8BED;&#x6CD5;&#x5757;</li>
<li>type&#x8BED;&#x6CD5;&#x5757;</li>
<li>service&#x8BED;&#x6CD5;&#x5757;</li>
<li>&#x9690;&#x85CF;&#x901A;&#x9053;</li>
</ul>
<blockquote>
<p>[!TIP]
&#x5728;&#x4EE5;&#x4E0A;&#x8BED;&#x6CD5;&#x7ED3;&#x6784;&#x4E2D;&#xFF0C;&#x5404;&#x4E2A;&#x8BED;&#x6CD5;&#x5757;&#x4ECE;&#x8BED;&#x6CD5;&#x4E0A;&#x6765;&#x8BF4;&#xFF0C;&#x6309;&#x7167;&#x8BED;&#x6CD5;&#x5757;&#x4E3A;&#x5355;&#x4F4D;&#xFF0C;&#x53EF;&#x4EE5;&#x5728;.api&#x6587;&#x4EF6;&#x4E2D;&#x4EFB;&#x610F;&#x4F4D;&#x7F6E;&#x58F0;&#x660E;&#xFF0C;
&#x4F46;&#x662F;&#x4E3A;&#x4E86;&#x63D0;&#x9AD8;&#x9605;&#x8BFB;&#x6548;&#x7387;&#xFF0C;&#x6211;&#x4EEC;&#x5EFA;&#x8BAE;&#x6309;&#x7167;&#x4EE5;&#x4E0A;&#x987A;&#x5E8F;&#x8FDB;&#x884C;&#x58F0;&#x660E;&#xFF0C;&#x56E0;&#x4E3A;&#x5728;&#x5C06;&#x6765;&#x53EF;&#x80FD;&#x4F1A;&#x901A;&#x8FC7;&#x4E25;&#x683C;&#x6A21;&#x5F0F;&#x6765;&#x63A7;&#x5236;&#x8BED;&#x6CD5;&#x5757;&#x7684;&#x987A;&#x5E8F;&#x3002;</p>
</blockquote>
<h3 id="syntax&#x8BED;&#x6CD5;&#x58F0;&#x660E;">syntax&#x8BED;&#x6CD5;&#x58F0;&#x660E;</h3>
<p>syntax&#x662F;&#x65B0;&#x52A0;&#x5165;&#x7684;&#x8BED;&#x6CD5;&#x7ED3;&#x6784;&#xFF0C;&#x8BE5;&#x8BED;&#x6CD5;&#x7684;&#x5F15;&#x5165;&#x53EF;&#x4EE5;&#x89E3;&#x51B3;&#xFF1A;</p>
<ul>
<li>&#x5FEB;&#x901F;&#x9488;&#x5BF9;api&#x7248;&#x672C;&#x5B9A;&#x4F4D;&#x5B58;&#x5728;&#x95EE;&#x9898;&#x7684;&#x8BED;&#x6CD5;&#x7ED3;&#x6784;</li>
<li>&#x9488;&#x5BF9;&#x7248;&#x672C;&#x505A;&#x8BED;&#x6CD5;&#x89E3;&#x6790;</li>
<li>&#x9632;&#x6B62;api&#x8BED;&#x6CD5;&#x5927;&#x7248;&#x672C;&#x5347;&#x7EA7;&#x5BFC;&#x81F4;&#x524D;&#x540E;&#x4E0D;&#x80FD;&#x5411;&#x524D;&#x517C;&#x5BB9;</li>
</ul>
<blockquote>
<p>**[!WARNING]
&#x88AB;import&#x7684;api&#x5FC5;&#x987B;&#x8981;&#x548C;main api&#x7684;syntax&#x7248;&#x672C;&#x4E00;&#x81F4;&#x3002;</p>
</blockquote>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<pre class="language-"><code class="lang-antlrv4">&apos;syntax&apos;={checkVersion(p)}STRING
</code></pre>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong></p>
<p>syntax&#xFF1A;&#x56FA;&#x5B9A;token&#xFF0C;&#x6807;&#x5FD7;&#x4E00;&#x4E2A;syntax&#x8BED;&#x6CD5;&#x7ED3;&#x6784;&#x7684;&#x5F00;&#x59CB;</p>
<p>checkVersion&#xFF1A;&#x81EA;&#x5B9A;&#x4E49;go&#x65B9;&#x6CD5;&#xFF0C;&#x68C0;&#x6D4B;<code>STRING</code>&#x662F;&#x5426;&#x4E3A;&#x4E00;&#x4E2A;&#x5408;&#x6CD5;&#x7684;&#x7248;&#x672C;&#x53F7;&#xFF0C;&#x76EE;&#x524D;&#x68C0;&#x6D4B;&#x903B;&#x8F91;&#x4E3A;&#xFF0C;STRING&#x5FC5;&#x987B;&#x662F;&#x6EE1;&#x8DB3;<code>(?m)&quot;v[1-9][0-9]*&quot;</code>&#x6B63;&#x5219;&#x3002;</p>
<p>STRING&#xFF1A;&#x4E00;&#x4E32;&#x82F1;&#x6587;&#x53CC;&#x5F15;&#x53F7;&#x5305;&#x88F9;&#x7684;&#x5B57;&#x7B26;&#x4E32;&#xFF0C;&#x5982;&quot;v1&quot;</p>
<p>&#x4E00;&#x4E2A;api&#x8BED;&#x6CD5;&#x6587;&#x4EF6;&#x53EA;&#x80FD;&#x6709;0&#x6216;&#x8005;1&#x4E2A;syntax&#x8BED;&#x6CD5;&#x58F0;&#x660E;&#xFF0C;&#x5982;&#x679C;&#x6CA1;&#x6709;syntax&#xFF0C;&#x5219;&#x9ED8;&#x8BA4;&#x4E3A;v1&#x7248;&#x672C;</p>
<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<p>eg1&#xFF1A;&#x4E0D;&#x89C4;&#x8303;&#x5199;&#x6CD5;</p>
<pre class="language-"><code class="lang-api">syntax=&quot;v1&quot;
</code></pre>
<p>eg2&#xFF1A;&#x89C4;&#x8303;&#x5199;&#x6CD5;(&#x63A8;&#x8350;)</p>
<pre class="language-"><code class="lang-api">syntax = &quot;v2&quot;
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<p>eg1&#xFF1A;</p>
<pre class="language-"><code class="lang-api">syntax = &quot;v0&quot;
</code></pre>
<p>eg2&#xFF1A;</p>
<pre class="language-"><code class="lang-api">syntax = v1
</code></pre>
<p>eg3&#xFF1A;</p>
<pre class="language-"><code class="lang-api">syntax = &quot;V1&quot;
</code></pre>
<h2 id="import&#x8BED;&#x6CD5;&#x5757;">import&#x8BED;&#x6CD5;&#x5757;</h2>
<p>&#x968F;&#x7740;&#x4E1A;&#x52A1;&#x89C4;&#x6A21;&#x589E;&#x5927;&#xFF0C;api&#x4E2D;&#x5B9A;&#x4E49;&#x7684;&#x7ED3;&#x6784;&#x4F53;&#x548C;&#x670D;&#x52A1;&#x8D8A;&#x6765;&#x8D8A;&#x591A;&#xFF0C;&#x6240;&#x6709;&#x7684;&#x8BED;&#x6CD5;&#x63CF;&#x8FF0;&#x5747;&#x4E3A;&#x4E00;&#x4E2A;api&#x6587;&#x4EF6;&#xFF0C;&#x8FD9;&#x662F;&#x591A;&#x4E48;&#x7CDF;&#x7CD5;&#x7684;&#x4E00;&#x4E2A;&#x95EE;&#x9898;&#xFF0C; &#x5176;&#x4F1A;&#x5927;&#x5927;&#x589E;&#x52A0;&#x4E86;&#x9605;&#x8BFB;&#x96BE;&#x5EA6;&#x548C;&#x7EF4;&#x62A4;&#x96BE;&#x5EA6;&#xFF0C;import&#x8BED;&#x6CD5;&#x5757;&#x53EF;&#x4EE5;&#x5E2E;&#x52A9;&#x6211;&#x4EEC;&#x89E3;&#x51B3;&#x8FD9;&#x4E2A;&#x95EE;&#x9898;&#xFF0C;&#x901A;&#x8FC7;&#x62C6;&#x5206;api&#x6587;&#x4EF6;&#xFF0C;
&#x4E0D;&#x540C;&#x7684;api&#x6587;&#x4EF6;&#x6309;&#x7167;&#x4E00;&#x5B9A;&#x89C4;&#x5219;&#x58F0;&#x660E;&#xFF0C;&#x53EF;&#x4EE5;&#x964D;&#x4F4E;&#x9605;&#x8BFB;&#x96BE;&#x5EA6;&#x548C;&#x7EF4;&#x62A4;&#x96BE;&#x5EA6;&#x3002;</p>
<blockquote>
<p>**[!WARNING]
&#x8FD9;&#x91CC;import&#x4E0D;&#x50CF;golang&#x90A3;&#x6837;&#x5305;&#x542B;package&#x58F0;&#x660E;&#xFF0C;&#x4EC5;&#x4EC5;&#x662F;&#x4E00;&#x4E2A;&#x6587;&#x4EF6;&#x8DEF;&#x5F84;&#x7684;&#x5F15;&#x5165;&#xFF0C;&#x6700;&#x7EC8;&#x89E3;&#x6790;&#x540E;&#x4F1A;&#x628A;&#x6240;&#x6709;&#x7684;&#x58F0;&#x660E;&#x90FD;&#x6C47;&#x805A;&#x5230;&#x4E00;&#x4E2A;spec.Spec&#x4E2D;&#x3002;
&#x4E0D;&#x80FD;import&#x591A;&#x4E2A;&#x76F8;&#x540C;&#x8DEF;&#x5F84;&#xFF0C;&#x5426;&#x5219;&#x4F1A;&#x89E3;&#x6790;&#x9519;&#x8BEF;&#x3002;</p>
</blockquote>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<pre class="language-"><code class="lang-antlrv4">&apos;import&apos; {checkImportValue(p)}STRING  
|&apos;import&apos; &apos;(&apos; ({checkImportValue(p)}STRING)+ &apos;)&apos;
</code></pre>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong></p>
<p>import&#xFF1A;&#x56FA;&#x5B9A;token&#xFF0C;&#x6807;&#x5FD7;&#x4E00;&#x4E2A;import&#x8BED;&#x6CD5;&#x7684;&#x5F00;&#x59CB;</p>
<p>checkImportValue&#xFF1A;&#x81EA;&#x5B9A;&#x4E49;go&#x65B9;&#x6CD5;&#xFF0C;&#x68C0;&#x6D4B;<code>STRING</code>&#x662F;&#x5426;&#x4E3A;&#x4E00;&#x4E2A;&#x5408;&#x6CD5;&#x7684;&#x6587;&#x4EF6;&#x8DEF;&#x5F84;&#xFF0C;&#x76EE;&#x524D;&#x68C0;&#x6D4B;&#x903B;&#x8F91;&#x4E3A;&#xFF0C;STRING&#x5FC5;&#x987B;&#x662F;&#x6EE1;&#x8DB3;<code>(?m)&quot;(/?[a-zA-Z0-9_#-])+\.api&quot;</code>&#x6B63;&#x5219;&#x3002;</p>
<p>STRING&#xFF1A;&#x4E00;&#x4E32;&#x82F1;&#x6587;&#x53CC;&#x5F15;&#x53F7;&#x5305;&#x88F9;&#x7684;&#x5B57;&#x7B26;&#x4E32;&#xFF0C;&#x5982;&quot;foo.api&quot;</p>
<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<p>eg&#xFF1A;</p>
<pre class="language-"><code class="lang-api">import &quot;foo.api&quot;
import &quot;foo/bar.api&quot;

import(
    &quot;bar.api&quot;
    &quot;foo/bar/foo.api&quot;
)
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<p>eg&#xFF1A;</p>
<pre class="language-"><code class="lang-api">import foo.api
import &quot;foo.txt&quot;
import (
    bar.api
    bar.api
)
</code></pre>
<h2 id="info&#x8BED;&#x6CD5;&#x5757;">info&#x8BED;&#x6CD5;&#x5757;</h2>
<p>info&#x8BED;&#x6CD5;&#x5757;&#x662F;&#x4E00;&#x4E2A;&#x5305;&#x542B;&#x4E86;&#x591A;&#x4E2A;&#x952E;&#x503C;&#x5BF9;&#x7684;&#x8BED;&#x6CD5;&#x4F53;&#xFF0C;&#x5176;&#x4F5C;&#x7528;&#x76F8;&#x5F53;&#x4E8E;&#x4E00;&#x4E2A;api&#x670D;&#x52A1;&#x7684;&#x63CF;&#x8FF0;&#xFF0C;&#x89E3;&#x6790;&#x5668;&#x4F1A;&#x5C06;&#x5176;&#x6620;&#x5C04;&#x5230;spec.Spec&#x4E2D;&#xFF0C; &#x4EE5;&#x5907;&#x7528;&#x4E8E;&#x7FFB;&#x8BD1;&#x6210;&#x5176;&#x4ED6;&#x8BED;&#x8A00;(golang&#x3001;java&#x7B49;)
&#x65F6;&#x9700;&#x8981;&#x643A;&#x5E26;&#x7684;meta&#x5143;&#x7D20;&#x3002;&#x5982;&#x679C;&#x4EC5;&#x4EC5;&#x662F;&#x5BF9;&#x5F53;&#x524D;api&#x7684;&#x4E00;&#x4E2A;&#x8BF4;&#x660E;&#xFF0C;&#x800C;&#x4E0D;&#x8003;&#x8651;&#x5176;&#x7FFB;&#x8BD1; &#x65F6;&#x4F20;&#x9012;&#x5230;&#x5176;&#x4ED6;&#x8BED;&#x8A00;&#xFF0C;&#x5219;&#x4F7F;&#x7528;&#x7B80;&#x5355;&#x7684;&#x591A;&#x884C;&#x6CE8;&#x91CA;&#x6216;&#x8005;java&#x98CE;&#x683C;&#x7684;&#x6587;&#x6863;&#x6CE8;&#x91CA;&#x5373;&#x53EF;&#xFF0C;&#x5173;&#x4E8E;&#x6CE8;&#x91CA;&#x8BF4;&#x660E;&#x8BF7;&#x53C2;&#x8003;&#x4E0B;&#x6587;&#x7684; <strong>&#x9690;&#x85CF;&#x901A;&#x9053;</strong>&#x3002;</p>
<blockquote>
<p>**[!WARNING]
&#x4E0D;&#x80FD;&#x4F7F;&#x7528;&#x91CD;&#x590D;&#x7684;key&#xFF0C;&#x6BCF;&#x4E2A;api&#x6587;&#x4EF6;&#x53EA;&#x80FD;&#x6709;0&#x6216;&#x8005;1&#x4E2A;info&#x8BED;&#x6CD5;&#x5757;</p>
</blockquote>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<pre class="language-"><code class="lang-antlrv4">&apos;info&apos; &apos;(&apos; (ID {checkKeyValue(p)}VALUE)+ &apos;)&apos;
</code></pre>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong></p>
<p>info&#xFF1A;&#x56FA;&#x5B9A;token&#xFF0C;&#x6807;&#x5FD7;&#x4E00;&#x4E2A;info&#x8BED;&#x6CD5;&#x5757;&#x7684;&#x5F00;&#x59CB;</p>
<p>checkKeyValue&#xFF1A;&#x81EA;&#x5B9A;&#x4E49;go&#x65B9;&#x6CD5;&#xFF0C;&#x68C0;&#x6D4B;<code>VALUE</code>&#x662F;&#x5426;&#x4E3A;&#x4E00;&#x4E2A;&#x5408;&#x6CD5;&#x503C;&#x3002;</p>
<p>VALUE&#xFF1A;key&#x5BF9;&#x5E94;&#x7684;&#x503C;&#xFF0C;&#x53EF;&#x4EE5;&#x4E3A;&#x5355;&#x884C;&#x7684;&#x9664;&apos;\r&apos;,&apos;\n&apos;,&apos;/&apos;&#x540E;&#x7684;&#x4EFB;&#x610F;&#x5B57;&#x7B26;&#xFF0C;&#x591A;&#x884C;&#x8BF7;&#x4EE5;&quot;&quot;&#x5305;&#x88F9;&#xFF0C;&#x4E0D;&#x8FC7;&#x5F3A;&#x70C8;&#x5EFA;&#x8BAE;&#x6240;&#x6709;&#x90FD;&#x4EE5;&quot;&quot;&#x5305;&#x88F9;</p>
<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<p>eg1&#xFF1A;&#x4E0D;&#x89C4;&#x8303;&#x5199;&#x6CD5;</p>
<pre class="language-"><code class="lang-api">info(
foo: foo value
bar:&quot;bar value&quot;
    desc:&quot;long long long long
long long text&quot;
)
</code></pre>
<p>eg2&#xFF1A;&#x89C4;&#x8303;&#x5199;&#x6CD5;(&#x63A8;&#x8350;)</p>
<pre class="language-"><code class="lang-api">info(
    foo: &quot;foo value&quot;
    bar: &quot;bar value&quot;
    desc: &quot;long long long long long long text&quot;
)
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<p>eg1&#xFF1A;&#x6CA1;&#x6709;key-value&#x5185;&#x5BB9;</p>
<pre class="language-"><code class="lang-api">info()
</code></pre>
<p>eg2&#xFF1A;&#x4E0D;&#x5305;&#x542B;&#x5192;&#x53F7;</p>
<pre class="language-"><code class="lang-api">info(
    foo value
)
</code></pre>
<p>eg3&#xFF1A;key-value&#x6CA1;&#x6709;&#x6362;&#x884C;</p>
<pre class="language-"><code class="lang-api">info(foo:&quot;value&quot;)
</code></pre>
<p>eg4&#xFF1A;&#x6CA1;&#x6709;key</p>
<pre class="language-"><code class="lang-api">info(
    : &quot;value&quot;
)
</code></pre>
<p>eg5&#xFF1A;&#x975E;&#x6CD5;&#x7684;key</p>
<pre class="language-"><code class="lang-api">info(
    12: &quot;value&quot;
)
</code></pre>
<p>eg6&#xFF1A;&#x79FB;&#x9664;&#x65E7;&#x7248;&#x672C;&#x591A;&#x884C;&#x8BED;&#x6CD5;</p>
<pre class="language-"><code class="lang-api">info(
    foo: &gt;
    some text
    &lt;
)
</code></pre>
<h2 id="type&#x8BED;&#x6CD5;&#x5757;">type&#x8BED;&#x6CD5;&#x5757;</h2>
<p>&#x5728;api&#x670D;&#x52A1;&#x4E2D;&#xFF0C;&#x6211;&#x4EEC;&#x9700;&#x8981;&#x7528;&#x5230;&#x4E00;&#x4E2A;&#x7ED3;&#x6784;&#x4F53;(&#x7C7B;)&#x6765;&#x4F5C;&#x4E3A;&#x8BF7;&#x6C42;&#x4F53;&#xFF0C;&#x54CD;&#x5E94;&#x4F53;&#x7684;&#x8F7D;&#x4F53;&#xFF0C;&#x56E0;&#x6B64;&#x6211;&#x4EEC;&#x9700;&#x8981;&#x58F0;&#x660E;&#x4E00;&#x4E9B;&#x7ED3;&#x6784;&#x4F53;&#x6765;&#x5B8C;&#x6210;&#x8FD9;&#x4EF6;&#x4E8B;&#x60C5;&#xFF0C; type&#x8BED;&#x6CD5;&#x5757;&#x7531;golang&#x7684;type&#x6F14;&#x53D8;&#x800C;&#x6765;&#xFF0C;&#x5F53;&#x7136;&#x4E5F;&#x4FDD;&#x7559;&#x7740;&#x4E00;&#x4E9B;golang type&#x7684;&#x7279;&#x6027;&#xFF0C;&#x6CBF;&#x7528;golang&#x7279;&#x6027;&#x6709;&#xFF1A;</p>
<ul>
<li>&#x4FDD;&#x7559;&#x4E86;golang&#x5185;&#x7F6E;&#x6570;&#x636E;&#x7C7B;&#x578B;<code>bool</code>,<code>int</code>,<code>int8</code>,<code>int16</code>,<code>int32</code>,<code>int64</code>,<code>uint</code>,<code>uint8</code>,<code>uint16</code>,<code>uint32</code>,<code>uint64</code>,<code>uintptr</code>
,<code>float32</code>,<code>float64</code>,<code>complex64</code>,<code>complex128</code>,<code>string</code>,<code>byte</code>,<code>rune</code>,</li>
<li>&#x517C;&#x5BB9;golang struct&#x98CE;&#x683C;&#x58F0;&#x660E;</li>
<li>&#x4FDD;&#x7559;golang&#x5173;&#x952E;&#x5B57;</li>
</ul>
<blockquote>
<p>**[!WARNING]&#xFE0F;</p>
<ul>
<li>&#x4E0D;&#x652F;&#x6301;alias</li>
<li>&#x4E0D;&#x652F;&#x6301;time.Time&#x6570;&#x636E;&#x7C7B;&#x578B;</li>
<li>&#x7ED3;&#x6784;&#x4F53;&#x540D;&#x79F0;&#x3001;&#x5B57;&#x6BB5;&#x540D;&#x79F0;&#x3001;&#x4E0D;&#x80FD;&#x4E3A;golang&#x5173;&#x952E;&#x5B57;</li>
</ul>
</blockquote>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<p>&#x7531;&#x4E8E;&#x5176;&#x548C;golang&#x76F8;&#x4F3C;&#xFF0C;&#x56E0;&#x6B64;&#x4E0D;&#x505A;&#x8BE6;&#x7EC6;&#x8BF4;&#x660E;&#xFF0C;&#x5177;&#x4F53;&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;&#x8BF7;&#x5728; <a href="https://github.com/tal-tech/go-zero/blob/master/tools/goctl/api/parser/g4/ApiParser.g4" target="_blank">ApiParser.g4</a> &#x4E2D;&#x67E5;&#x770B;typeSpec&#x5B9A;&#x4E49;&#x3002;</p>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong></p>
<p>&#x53C2;&#x8003;golang&#x5199;&#x6CD5;</p>
<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<p>eg1&#xFF1A;&#x4E0D;&#x89C4;&#x8303;&#x5199;&#x6CD5;</p>
<pre class="language-"><code class="lang-api">type Foo struct{
    Id int `path:&quot;id&quot;` // &#x2460;
    Foo int `json:&quot;foo&quot;`
}

type Bar struct{
    // &#x975E;&#x5BFC;&#x51FA;&#x578B;&#x5B57;&#x6BB5;
    bar int `form:&quot;bar&quot;`
}

type(
    // &#x975E;&#x5BFC;&#x51FA;&#x578B;&#x7ED3;&#x6784;&#x4F53;
    fooBar struct{
        FooBar int
    }
)
</code></pre>
<p>eg2&#xFF1A;&#x89C4;&#x8303;&#x5199;&#x6CD5;&#xFF08;&#x63A8;&#x8350;&#xFF09;</p>
<pre class="language-"><code class="lang-api">type Foo{
    Id int `path:&quot;id&quot;`
    Foo int `json:&quot;foo&quot;`
}

type Bar{
    Bar int `form:&quot;bar&quot;`
}

type(
    FooBar{
        FooBar int
    }
)
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<p>eg</p>
<pre class="language-"><code class="lang-api">type Gender int // &#x4E0D;&#x652F;&#x6301;

// &#x975E;struct token
type Foo structure{ 
  CreateTime time.Time // &#x4E0D;&#x652F;&#x6301;time.Time
}

// golang&#x5173;&#x952E;&#x5B57; var
type var{} 

type Foo{
  // golang&#x5173;&#x952E;&#x5B57; interface
  Foo interface 
}


type Foo{
  foo int 
  // map key&#x5FC5;&#x987B;&#x8981;golang&#x5185;&#x7F6E;&#x6570;&#x636E;&#x7C7B;&#x578B;
  m map[Bar]string
}
</code></pre>
<blockquote>
<p>[!NOTE]  &#x2460;
tag&#x5B9A;&#x4E49;&#x548C;golang&#x4E2D;json tag&#x8BED;&#x6CD5;&#x4E00;&#x6837;&#xFF0C;&#x9664;&#x4E86;json tag&#x5916;&#xFF0C;go-zero&#x8FD8;&#x63D0;&#x4F9B;&#x4E86;&#x53E6;&#x5916;&#x4E00;&#x4E9B;tag&#x6765;&#x5B9E;&#x73B0;&#x5BF9;&#x5B57;&#x6BB5;&#x7684;&#x63CF;&#x8FF0;&#xFF0C;
&#x8BE6;&#x60C5;&#x89C1;&#x4E0B;&#x8868;&#x3002;</p>
</blockquote>
<ul>
<li>tag&#x8868;<table>
<tr>
  <td>tag key</td> <td>&#x63CF;&#x8FF0;</td> <td>&#x63D0;&#x4F9B;&#x65B9;</td><td>&#x6709;&#x6548;&#x8303;&#x56F4; </td> <td>&#x793A;&#x4F8B; </td>
</tr>
<tr> 
<td>json</td> <td>json&#x5E8F;&#x5217;&#x5316;tag</td> <td>golang</td> <td>request&#x3001;response</td> <td><code>json:&quot;fooo&quot;</code></td>
</tr>
<tr>
<td>path</td> <td>&#x8DEF;&#x7531;path&#xFF0C;&#x5982;<code>/foo/:id</code></td> <td>go-zero</td> <td>request</td> <td><code>path:&quot;id&quot;</code></td>
</tr>
<tr>
<td>form</td> <td>&#x6807;&#x5FD7;&#x8BF7;&#x6C42;&#x4F53;&#x662F;&#x4E00;&#x4E2A;form&#xFF08;POST&#x65B9;&#x6CD5;&#x65F6;&#xFF09;&#x6216;&#x8005;&#x4E00;&#x4E2A;query(GET&#x65B9;&#x6CD5;&#x65F6;<code>/search?name=keyword</code>)</td> <td>go-zero</td> <td>request</td> <td><code>form:&quot;name&quot;</code></td>
</tr>
</table></li>
<li><p>tag&#x4FEE;&#x9970;&#x7B26;</p>
<p>&#x5E38;&#x89C1;&#x53C2;&#x6570;&#x6821;&#x9A8C;&#x63CF;&#x8FF0;</p>
<table>
<tr>
<td>tag key </td> <td>&#x63CF;&#x8FF0; </td> <td>&#x63D0;&#x4F9B;&#x65B9; </td> <td>&#x6709;&#x6548;&#x8303;&#x56F4; </td> <td>&#x793A;&#x4F8B; </td>
</tr>
<tr>
<td>optional</td> <td>&#x5B9A;&#x4E49;&#x5F53;&#x524D;&#x5B57;&#x6BB5;&#x4E3A;&#x53EF;&#x9009;&#x53C2;&#x6570;</td> <td>go-zero</td> <td>request</td> <td><code>json:&quot;name,optional&quot;</code></td>
</tr>
<tr>
<td>options</td> <td>&#x5B9A;&#x4E49;&#x5F53;&#x524D;&#x5B57;&#x6BB5;&#x7684;&#x679A;&#x4E3E;&#x503C;,&#x591A;&#x4E2A;&#x4EE5;&#x7AD6;&#x7EBF;|&#x9694;&#x5F00;</td> <td>go-zero</td> <td>request</td> <td><code>json:&quot;gender,options=male&quot;</code></td>
</tr>
<tr>
<td>default</td> <td>&#x5B9A;&#x4E49;&#x5F53;&#x524D;&#x5B57;&#x6BB5;&#x9ED8;&#x8BA4;&#x503C;</td> <td>go-zero</td> <td>request</td> <td><code>json:&quot;gender,default=male&quot;</code></td>
</tr>
<tr>
<td>range</td> <td>&#x5B9A;&#x4E49;&#x5F53;&#x524D;&#x5B57;&#x6BB5;&#x6570;&#x503C;&#x8303;&#x56F4;</td> <td>go-zero</td> <td>request</td> <td><code>json:&quot;age,range=[0:120]&quot;</code></td>
</tr>
</table>

<blockquote>
<p>[!TIP]
tag&#x4FEE;&#x9970;&#x7B26;&#x9700;&#x8981;&#x5728;tag value&#x540E;&#x4EE5;&#x5F15;&#x6587;&#x9017;&#x53F7;,&#x9694;&#x5F00;</p>
</blockquote>
</li>
</ul>
<h2 id="service&#x8BED;&#x6CD5;&#x5757;">service&#x8BED;&#x6CD5;&#x5757;</h2>
<p>service&#x8BED;&#x6CD5;&#x5757;&#x7528;&#x4E8E;&#x5B9A;&#x4E49;api&#x670D;&#x52A1;&#xFF0C;&#x5305;&#x542B;&#x670D;&#x52A1;&#x540D;&#x79F0;&#xFF0C;&#x670D;&#x52A1;metadata&#xFF0C;&#x4E2D;&#x95F4;&#x4EF6;&#x58F0;&#x660E;&#xFF0C;&#x8DEF;&#x7531;&#xFF0C;handler&#x7B49;&#x3002;</p>
<blockquote>
<p>**[!WARNING]&#xFE0F;</p>
<ul>
<li>main api&#x548C;&#x88AB;import&#x7684;api&#x670D;&#x52A1;&#x540D;&#x79F0;&#x5FC5;&#x987B;&#x4E00;&#x81F4;&#xFF0C;&#x4E0D;&#x80FD;&#x51FA;&#x73B0;&#x670D;&#x52A1;&#x540D;&#x79F0;&#x6B67;&#x4E49;&#x3002;</li>
<li>handler&#x540D;&#x79F0;&#x4E0D;&#x80FD;&#x91CD;&#x590D;</li>
<li>&#x8DEF;&#x7531;&#xFF08;&#x8BF7;&#x6C42;&#x65B9;&#x6CD5;+&#x8BF7;&#x6C42;path&#xFF09;&#x540D;&#x79F0;&#x4E0D;&#x80FD;&#x91CD;&#x590D;</li>
<li>&#x8BF7;&#x6C42;&#x4F53;&#x5FC5;&#x987B;&#x58F0;&#x660E;&#x4E3A;&#x666E;&#x901A;&#xFF08;&#x975E;&#x6307;&#x9488;&#xFF09;struct&#xFF0C;&#x54CD;&#x5E94;&#x4F53;&#x505A;&#x4E86;&#x4E00;&#x4E9B;&#x5411;&#x524D;&#x517C;&#x5BB9;&#x5904;&#x7406;&#xFF0C;&#x8BE6;&#x8BF7;&#x89C1;&#x4E0B;&#x6587;&#x8BF4;&#x660E;</li>
</ul>
</blockquote>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<pre class="language-"><code class="lang-antlrv4">serviceSpec:    atServer? serviceApi;
atServer:       &apos;@server&apos; lp=&apos;(&apos; kvLit+ rp=&apos;)&apos;;
serviceApi:     {match(p,&quot;service&quot;)}serviceToken=ID serviceName lbrace=&apos;{&apos; serviceRoute* rbrace=&apos;}&apos;;
serviceRoute:   atDoc? (atServer|atHandler) route;
atDoc:          &apos;@doc&apos; lp=&apos;(&apos;? ((kvLit+)|STRING) rp=&apos;)&apos;?;
atHandler:      &apos;@handler&apos; ID;
route:          {checkHttpMethod(p)}httpMethod=ID path request=body? returnToken=ID? response=replybody?;
body:           lp=&apos;(&apos; (ID)? rp=&apos;)&apos;;
replybody:      lp=&apos;(&apos; dataType? rp=&apos;)&apos;;
// kv
kvLit:          key=ID {checkKeyValue(p)}value=LINE_VALUE;

serviceName:    (ID &apos;-&apos;?)+;
path:           ((&apos;/&apos; (ID (&apos;-&apos; ID)*))|(&apos;/:&apos; (ID (&apos;-&apos; ID)?)))+;
</code></pre>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong></p>
<p>serviceSpec&#xFF1A;&#x5305;&#x542B;&#x4E86;&#x4E00;&#x4E2A;&#x53EF;&#x9009;&#x8BED;&#x6CD5;&#x5757;<code>atServer</code>&#x548C;<code>serviceApi</code>&#x8BED;&#x6CD5;&#x5757;&#xFF0C;&#x5176;&#x9075;&#x5FAA;&#x5E8F;&#x5217;&#x6A21;&#x5F0F;&#xFF08;&#x7F16;&#x5199;service&#x5FC5;&#x987B;&#x8981;&#x6309;&#x7167;&#x987A;&#x5E8F;&#xFF0C;&#x5426;&#x5219;&#x4F1A;&#x89E3;&#x6790;&#x51FA;&#x9519;&#xFF09;</p>
<p>atServer&#xFF1A; &#x53EF;&#x9009;&#x8BED;&#x6CD5;&#x5757;&#xFF0C;&#x5B9A;&#x4E49;key-value&#x7ED3;&#x6784;&#x7684;server metadata&#xFF0C;&apos;@server&apos;
&#x8868;&#x793A;&#x8FD9;&#x4E00;&#x4E2A;server&#x8BED;&#x6CD5;&#x5757;&#x7684;&#x5F00;&#x59CB;&#xFF0C;&#x5176;&#x53EF;&#x4EE5;&#x7528;&#x4E8E;&#x63CF;&#x8FF0;serviceApi&#x6216;&#x8005;route&#x8BED;&#x6CD5;&#x5757;&#xFF0C;&#x5176;&#x7528;&#x4E8E;&#x63CF;&#x8FF0;&#x4E0D;&#x540C;&#x8BED;&#x6CD5;&#x5757;&#x65F6;&#x6709;&#x4E00;&#x4E9B;&#x7279;&#x6B8A;&#x5173;&#x952E;key &#x9700;&#x8981;&#x503C;&#x5F97;&#x6CE8;&#x610F;&#xFF0C;&#x89C1; <strong>atServer&#x5173;&#x952E;key&#x63CF;&#x8FF0;&#x8BF4;&#x660E;</strong>&#x3002;</p>
<p>serviceApi&#xFF1A;&#x5305;&#x542B;&#x4E86;1&#x5230;&#x591A;&#x4E2A;<code>serviceRoute</code>&#x8BED;&#x6CD5;&#x5757;</p>
<p>serviceRoute&#xFF1A;&#x6309;&#x7167;&#x5E8F;&#x5217;&#x6A21;&#x5F0F;&#x5305;&#x542B;&#x4E86;<code>atDoc</code>,handler&#x548C;<code>route</code></p>
<p>atDoc&#xFF1A;&#x53EF;&#x9009;&#x8BED;&#x6CD5;&#x5757;&#xFF0C;&#x4E00;&#x4E2A;&#x8DEF;&#x7531;&#x7684;key-value&#x63CF;&#x8FF0;&#xFF0C;&#x5176;&#x5728;&#x89E3;&#x6790;&#x540E;&#x4F1A;&#x4F20;&#x9012;&#x5230;spec.Spec&#x7ED3;&#x6784;&#x4F53;&#xFF0C;&#x5982;&#x679C;&#x4E0D;&#x5173;&#x5FC3;&#x4F20;&#x9012;&#x5230;spec.Spec, &#x63A8;&#x8350;&#x7528;&#x5355;&#x884C;&#x6CE8;&#x91CA;&#x66FF;&#x4EE3;&#x3002;</p>
<p>handler&#xFF1A;&#x662F;&#x5BF9;&#x8DEF;&#x7531;&#x7684;handler&#x5C42;&#x63CF;&#x8FF0;&#xFF0C;&#x53EF;&#x4EE5;&#x901A;&#x8FC7;atServer&#x6307;&#x5B9A;<code>handler</code> key&#x6765;&#x6307;&#x5B9A;handler&#x540D;&#x79F0;&#xFF0C; &#x4E5F;&#x53EF;&#x4EE5;&#x76F4;&#x63A5;&#x7528;atHandler&#x8BED;&#x6CD5;&#x5757;&#x6765;&#x5B9A;&#x4E49;handler&#x540D;&#x79F0;</p>
<p>atHandler&#xFF1A;&apos;@handler&apos; &#x56FA;&#x5B9A;token&#xFF0C;&#x540E;&#x63A5;&#x4E00;&#x4E2A;&#x9075;&#x5FAA;&#x6B63;&#x5219;<code>[_a-zA-Z][a-zA-Z_-]*</code>)&#x7684;&#x503C;&#xFF0C;&#x7528;&#x4E8E;&#x58F0;&#x660E;&#x4E00;&#x4E2A;handler&#x540D;&#x79F0;</p>
<p>route&#xFF1A;&#x8DEF;&#x7531;&#xFF0C;&#x6709;<code>httpMethod</code>&#x3001;<code>path</code>&#x3001;&#x53EF;&#x9009;<code>request</code>&#x3001;&#x53EF;&#x9009;<code>response</code>&#x7EC4;&#x6210;&#xFF0C;<code>httpMethod</code>&#x662F;&#x5FC5;&#x987B;&#x662F;&#x5C0F;&#x5199;&#x3002;</p>
<p>body&#xFF1A;api&#x8BF7;&#x6C42;&#x4F53;&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;&#xFF0C;&#x5FC5;&#x987B;&#x8981;&#x7531;()&#x5305;&#x88F9;&#x7684;&#x53EF;&#x9009;&#x7684;ID&#x503C;</p>
<p>replyBody&#xFF1A;api&#x54CD;&#x5E94;&#x4F53;&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;&#xFF0C;&#x5FC5;&#x987B;&#x7531;()&#x5305;&#x88F9;&#x7684;struct&#x3001;<del>array(&#x5411;&#x524D;&#x517C;&#x5BB9;&#x5904;&#x7406;&#xFF0C;&#x540E;&#x7EED;&#x53EF;&#x80FD;&#x4F1A;&#x5E9F;&#x5F03;&#xFF0C;&#x5F3A;&#x70C8;&#x63A8;&#x8350;&#x4EE5;struct&#x5305;&#x88F9;&#xFF0C;&#x4E0D;&#x8981;&#x76F4;&#x63A5;&#x7528;array&#x4F5C;&#x4E3A;&#x54CD;&#x5E94;&#x4F53;)</del></p>
<p>kvLit&#xFF1A; &#x540C;info key-value</p>
<p>serviceName: &#x53EF;&#x4EE5;&#x6709;&#x591A;&#x4E2A;&apos;-&apos;join&#x7684;ID&#x503C;</p>
<p>path&#xFF1A;api&#x8BF7;&#x6C42;&#x8DEF;&#x5F84;&#xFF0C;&#x5FC5;&#x987B;&#x4EE5;&apos;/&apos;&#x6216;&#x8005;&apos;/:&apos;&#x5F00;&#x5934;&#xFF0C;&#x5207;&#x4E0D;&#x80FD;&#x4EE5;&apos;/&apos;&#x7ED3;&#x5C3E;&#xFF0C;&#x4E2D;&#x95F4;&#x53EF;&#x5305;&#x542B;ID&#x6216;&#x8005;&#x591A;&#x4E2A;&#x4EE5;&apos;-&apos;join&#x7684;ID&#x5B57;&#x7B26;&#x4E32;</p>
<p><strong>atServer&#x5173;&#x952E;key&#x63CF;&#x8FF0;&#x8BF4;&#x660E;</strong></p>
<p>&#x4FEE;&#x9970;service&#x65F6;</p>
<table>
<tr>
<td>key</td><td>&#x63CF;&#x8FF0;</td><td>&#x793A;&#x4F8B;</td>
</tr>
<tr>
<td>jwt</td><td>&#x58F0;&#x660E;&#x5F53;&#x524D;service&#x4E0B;&#x6240;&#x6709;&#x8DEF;&#x7531;&#x9700;&#x8981;jwt&#x9274;&#x6743;&#xFF0C;&#x4E14;&#x4F1A;&#x81EA;&#x52A8;&#x751F;&#x6210;&#x5305;&#x542B;jwt&#x903B;&#x8F91;&#x7684;&#x4EE3;&#x7801;</td><td><code>jwt: Auth</code></td>
</tr>
<tr>
<td>group</td><td>&#x58F0;&#x660E;&#x5F53;&#x524D;service&#x6216;&#x8005;&#x8DEF;&#x7531;&#x6587;&#x4EF6;&#x5206;&#x7EC4;</td><td><code>group: login</code></td>
</tr>
<tr>
<td>middleware</td><td>&#x58F0;&#x660E;&#x5F53;&#x524D;service&#x9700;&#x8981;&#x5F00;&#x542F;&#x4E2D;&#x95F4;&#x4EF6;</td><td><code>middleware: AuthMiddleware</code></td>
</tr>
</table>

<p>&#x4FEE;&#x9970;route&#x65F6;</p>
<table>
<tr>
<td>key</td><td>&#x63CF;&#x8FF0;</td><td>&#x793A;&#x4F8B;</td>
</tr>
<tr>
<td>handler</td><td>&#x58F0;&#x660E;&#x4E00;&#x4E2A;handler</td><td>-</td>
</tr>
</table>

<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<p>eg1&#xFF1A;&#x4E0D;&#x89C4;&#x8303;&#x5199;&#x6CD5;</p>
<pre class="language-"><code class="lang-api">@server(
  jwt: Auth
  group: foo
  middleware: AuthMiddleware
)
service foo-api{
  @doc(
    summary: foo
  )
  @server(
    handler: foo
  )
  // &#x975E;&#x5BFC;&#x51FA;&#x578B;body
  post /foo/:id (foo) returns (bar)

  @doc &quot;bar&quot;
  @handler bar
  post /bar returns ([]int)// &#x4E0D;&#x63A8;&#x8350;&#x6570;&#x7EC4;&#x4F5C;&#x4E3A;&#x54CD;&#x5E94;&#x4F53;

  @handler fooBar
  post /foo/bar (Foo) returns // &#x53EF;&#x4EE5;&#x7701;&#x7565;&apos;returns&apos;
}
</code></pre>
<p>eg2&#xFF1A;&#x89C4;&#x8303;&#x5199;&#x6CD5;&#xFF08;&#x63A8;&#x8350;&#xFF09;</p>
<pre class="language-"><code class="lang-api">@server(
  jwt: Auth
  group: foo
  middleware: AuthMiddleware
)
service foo-api{
  @doc &quot;foo&quot;
  @handler: foo
  post /foo/:id (Foo) returns (Bar)
}

service foo-api{
  @handler ping
  get /ping

  @doc &quot;foo&quot;
  @handler: bar
  post /bar/:id (Foo)
}
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<pre class="language-"><code class="lang-api">// &#x4E0D;&#x652F;&#x6301;&#x7A7A;&#x7684;server&#x8BED;&#x6CD5;&#x5757;
@server(
)
// &#x4E0D;&#x652F;&#x6301;&#x7A7A;&#x7684;service&#x8BED;&#x6CD5;&#x5757;
service foo-api{
}

service foo-api{
  @doc kkkk // &#x7B80;&#x7248;doc&#x5FC5;&#x987B;&#x7528;&#x82F1;&#x6587;&#x53CC;&#x5F15;&#x53F7;&#x5F15;&#x8D77;&#x6765;
  @handler foo
  post /foo

  @handler foo // &#x91CD;&#x590D;&#x7684;handler
  post /bar

  @handler fooBar
  post /bar // &#x91CD;&#x590D;&#x7684;&#x8DEF;&#x7531;

  // @handler&#x548C;@doc&#x987A;&#x5E8F;&#x9519;&#x8BEF;
  @handler someHandler
  @doc &quot;some doc&quot;
  post /some/path

  // handler&#x7F3A;&#x5931;
  post /some/path/:id

  @handler reqTest
  post /foo/req (*Foo) // &#x4E0D;&#x652F;&#x6301;&#x9664;&#x666E;&#x901A;&#x7ED3;&#x6784;&#x4F53;&#x5916;&#x7684;&#x5176;&#x4ED6;&#x6570;&#x636E;&#x7C7B;&#x578B;&#x4F5C;&#x4E3A;&#x8BF7;&#x6C42;&#x4F53;

  @handler replyTest
  post /foo/reply returns (*Foo) // &#x4E0D;&#x652F;&#x6301;&#x9664;&#x666E;&#x901A;&#x7ED3;&#x6784;&#x4F53;&#x3001;&#x6570;&#x7EC4;(&#x5411;&#x524D;&#x517C;&#x5BB9;&#xFF0C;&#x540E;&#x7EED;&#x8003;&#x8651;&#x5E9F;&#x5F03;)&#x5916;&#x7684;&#x5176;&#x4ED6;&#x6570;&#x636E;&#x7C7B;&#x578B;&#x4F5C;&#x4E3A;&#x54CD;&#x5E94;&#x4F53;
}
</code></pre>
<h2 id="&#x9690;&#x85CF;&#x901A;&#x9053;">&#x9690;&#x85CF;&#x901A;&#x9053;</h2>
<p>&#x9690;&#x85CF;&#x901A;&#x9053;&#x76EE;&#x524D;&#x4E3B;&#x8981;&#x4E3A;&#x7A7A;&#x767D;&#x7B26;&#x53F7;&#x3001;&#x6362;&#x884C;&#x7B26;&#x53F7;&#x4EE5;&#x53CA;&#x6CE8;&#x91CA;&#xFF0C;&#x8FD9;&#x91CC;&#x6211;&#x4EEC;&#x53EA;&#x8BF4;&#x6CE8;&#x91CA;&#xFF0C;&#x56E0;&#x4E3A;&#x7A7A;&#x767D;&#x7B26;&#x53F7;&#x548C;&#x6362;&#x884C;&#x7B26;&#x53F7;&#x6211;&#x4EEC;&#x76EE;&#x524D;&#x62FF;&#x6765;&#x4E5F;&#x65E0;&#x7528;&#x3002;</p>
<h3 id="&#x5355;&#x884C;&#x6CE8;&#x91CA;">&#x5355;&#x884C;&#x6CE8;&#x91CA;</h3>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<pre class="language-"><code class="lang-antlrv4">&apos;//&apos; ~[\r\n]*
</code></pre>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong>
&#x7531;&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;&#x53EF;&#x77E5;&#x9053;&#xFF0C;&#x5355;&#x884C;&#x6CE8;&#x91CA;&#x5FC5;&#x987B;&#x8981;&#x4EE5;<code>//</code>&#x5F00;&#x5934;&#xFF0C;&#x5185;&#x5BB9;&#x4E3A;&#x4E0D;&#x80FD;&#x5305;&#x542B;&#x6362;&#x884C;&#x7B26;</p>
<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<pre class="language-"><code class="lang-api">// doc
// comment
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<pre class="language-"><code class="lang-api">// break
line comments
</code></pre>
<h3 id="java&#x98CE;&#x683C;&#x6587;&#x6863;&#x6CE8;&#x91CA;">java&#x98CE;&#x683C;&#x6587;&#x6863;&#x6CE8;&#x91CA;</h3>
<p><strong>&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;</strong></p>
<pre class="language-"><code class="lang-antlrv4">&apos;/*&apos; .*? &apos;*/&apos;
</code></pre>
<p><strong>&#x8BED;&#x6CD5;&#x8BF4;&#x660E;</strong></p>
<p>&#x7531;&#x8BED;&#x6CD5;&#x5B9A;&#x4E49;&#x53EF;&#x77E5;&#x9053;&#xFF0C;&#x5355;&#x884C;&#x6CE8;&#x91CA;&#x5FC5;&#x987B;&#x8981;&#x4EE5;<code>/*</code>&#x5F00;&#x5934;&#xFF0C;<code>*/</code>&#x7ED3;&#x5C3E;&#x7684;&#x4EFB;&#x610F;&#x5B57;&#x7B26;&#x3002;</p>
<p><strong>&#x6B63;&#x786E;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x2705;</p>
<pre class="language-"><code class="lang-api">/**
 * java-style doc
 */
</code></pre>
<p><strong>&#x9519;&#x8BEF;&#x8BED;&#x6CD5;&#x793A;&#x4F8B;</strong> &#x274C;</p>
<pre class="language-"><code class="lang-api">/*
 * java-style doc */
 */
</code></pre>
<h2 id="doccomment">Doc&amp;Comment</h2>
<p>&#x5982;&#x679C;&#x60F3;&#x83B7;&#x53D6;&#x67D0;&#x4E00;&#x4E2A;&#x5143;&#x7D20;&#x7684;doc&#x6216;&#x8005;comment&#x5F00;&#x53D1;&#x4EBA;&#x5458;&#x9700;&#x8981;&#x600E;&#x4E48;&#x5B9A;&#x4E49;&#xFF1F;</p>
<p><strong>Doc</strong></p>
<p>&#x6211;&#x4EEC;&#x89C4;&#x5B9A;&#x4E0A;&#x4E00;&#x4E2A;&#x8BED;&#x6CD5;&#x5757;&#xFF08;&#x975E;&#x9690;&#x85CF;&#x901A;&#x9053;&#x5185;&#x5BB9;&#xFF09;&#x7684;&#x884C;&#x6570;line+1&#x5230;&#x5F53;&#x524D;&#x8BED;&#x6CD5;&#x5757;&#x7B2C;&#x4E00;&#x4E2A;&#x5143;&#x7D20;&#x524D;&#x7684;&#x6240;&#x6709;&#x6CE8;&#x91CA;(&#x5F53;&#x884C;&#xFF0C;&#x6216;&#x8005;&#x591A;&#x884C;)&#x5747;&#x4E3A;doc&#xFF0C; &#x4E14;&#x4FDD;&#x7559;&#x4E86;<code>//</code>&#x3001;<code>/*</code>&#x3001;<code>*/</code>&#x539F;&#x59CB;&#x6807;&#x8BB0;&#x3002;</p>
<p><strong>Comment</strong></p>
<p>&#x6211;&#x4EEC;&#x89C4;&#x5B9A;&#x5F53;&#x524D;&#x8BED;&#x6CD5;&#x5757;&#x6700;&#x540E;&#x4E00;&#x4E2A;&#x5143;&#x7D20;&#x6240;&#x5728;&#x884C;&#x5F00;&#x59CB;&#x7684;&#x4E00;&#x4E2A;&#x6CE8;&#x91CA;&#x5757;(&#x5F53;&#x884C;&#xFF0C;&#x6216;&#x8005;&#x591A;&#x884C;)&#x4E3A;comment &#x4E14;&#x4FDD;&#x7559;&#x4E86;<code>//</code>&#x3001;<code>/*</code>&#x3001;<code>*/</code>&#x539F;&#x59CB;&#x6807;&#x8BB0;&#x3002;
&#x8BED;&#x6CD5;&#x5757;Doc&#x548C;Comment&#x7684;&#x652F;&#x6301;&#x60C5;&#x51B5;</p>
<table>
<tr>
  <td>&#x8BED;&#x6CD5;&#x5757;</td><td>parent&#x8BED;&#x6CD5;&#x5757;</td><td>Doc</td><td>Comment</td>
</tr>
<tr>
  <td>syntaxLit</td><td>api</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
<tr>
  <td>kvLit</td><td>infoSpec</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
<tr>
  <td>importLit</td><td>importSpec</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
<tr>
  <td>typeLit</td><td>api</td><td>&#x2705;</td><td>&#x274C;</td>
</tr>
<tr>
  <td>typeLit</td><td>typeBlock</td><td>&#x2705;</td><td>&#x274C;</td>
</tr>
<tr>
  <td>field</td><td>typeLit</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
<tr>
  <td>key-value</td><td>atServer</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
<tr>
  <td>atHandler</td><td>serviceRoute</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
<tr>
  <td>route</td><td>serviceRoute</td><td>&#x2705;</td><td>&#x2705;</td>
</tr>
</table>

<p>&#x4EE5;&#x4E0B;&#x4E3A;&#x5BF9;&#x5E94;&#x8BED;&#x6CD5;&#x5757;&#x89E3;&#x6790;&#x540E;&#x7EC6;&#x5E26;doc&#x548C;comment&#x7684;&#x5199;&#x6CD5;</p>
<pre class="language-"><code class="lang-api">// syntaxLit doc
syntax = &quot;v1&quot; // syntaxLit commnet

info(
  // kvLit doc
  author: songmeizi // kvLit comment
)

// typeLit doc
type Foo {}

type(
  // typeLit doc
  Bar{}

  FooBar{
    // filed doc
    Name int // filed comment
  }
)

@server(
  /**
   * kvLit doc
   * &#x5F00;&#x542F;jwt&#x9274;&#x6743;
   */
  jwt: Auth /**kvLit comment*/
)
service foo-api{
  // atHandler doc
  @handler foo //atHandler comment

  /*
   * route doc
   * post&#x8BF7;&#x6C42;
   * path&#x4E3A; /foo
   * &#x8BF7;&#x6C42;&#x4F53;&#xFF1A;Foo
   * &#x54CD;&#x5E94;&#x4F53;&#xFF1A;Foo
   */
  post /foo (Foo) returns (Foo) // route comment
}
</code></pre>
<p><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.css"></p>
<script src="./javascript/gitalk.js"></script>
<div id="gitalk-container"></div>
<script>
var gitalk = new Gitalk({
  "clientID": "b9f61eecd453fb93cefc",
  "clientSecret": "8e70a3944fa689c13136aa56ea5bfb9945802bd2",
  "repo": "go-zero-doc",
  "owner": "zeromicro",
  "admin": ["anqiansong"],
  "id": window.location.pathname,      
  "distractionFreeMode": false  
});
gitalk.render("gitalk-container");
</script>


<footer class="page-footer"><span class="copyright">Copyright &#xA9; 2019-2021 go-zero all right reserved&#xFF0C;powered by Gitbook</span><span class="footer-modification">&#x6700;&#x540E;&#x66F4;&#x65B0;&#x65F6;&#x95F4;&#xFF1A;
2021-04-10 07:21:07
</span></footer>
<script>console.log("plugin-popup....");document.onclick = function(e){ e.target.tagName === "IMG" && window.open(e.target.src,e.target.src)}</script><style>img{cursor:pointer}</style>
                                
                                </section>
                            
    </div>
    <div class="search-results">
        <div class="has-results">
            
            <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
            <ul class="search-results-list"></ul>
            
        </div>
        <div class="no-results">
            
            <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
            
        </div>
    </div>
</div>

                        </div>
                    </div>
                
            </div>

            
                <a href="go-zero-features.html" class="navigation navigation-prev " aria-label="Previous page: go-zero特点">
                    <i class="fa fa-angle-left"></i>
                </a>
                
                
                <a href="api-dir.html" class="navigation navigation-next " aria-label="Next page: api目录结构">
                    <i class="fa fa-angle-right"></i>
                </a>
                
            
    </div>

    <script>
        var gitbook = gitbook || [];
        gitbook.push(function() {
            gitbook.page.hasChanged({"page":{"title":"api语法介绍","level":"1.6.3","depth":2,"next":{"title":"api目录结构","level":"1.6.4","depth":2,"path":"api-dir.md","ref":"api-dir.md","articles":[]},"previous":{"title":"go-zero特点","level":"1.6.2","depth":2,"path":"go-zero-features.md","ref":"go-zero-features.md","articles":[]},"dir":"ltr"},"config":{"plugins":["back-to-top-button","chapter-fold","code","-lunr","-search","search-pro","github","splitter","-sharing","sharing-plus","tbfed-pagefooter","flexible-alerts","page-toc-button","pageview-count","popup","hide-element","edit-link","-highlight","prism","theme-comscore"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"tbfed-pagefooter":{"copyright":"Copyright © 2019-2021 go-zero","modify_label":"最后更新时间：","modify_format":"YYYY-MM-DD HH:mm:ss"},"chapter-fold":{},"prism":{"lang":{"shell":"bash"},"css":["prismjs/themes/prism-tomorrow.css"]},"github":{"url":"https://github.com/tal-tech/go-zero"},"splitter":{},"search-pro":{},"sharing-plus":{"qq":false,"all":["facebook","google","twitter","instapaper","linkedin","pocket","stumbleupon"],"douban":false,"facebook":true,"weibo":false,"instapaper":false,"whatsapp":false,"hatenaBookmark":false,"twitter":true,"messenger":false,"line":false,"vk":false,"pocket":true,"google":false,"viber":false,"stumbleupon":false,"qzone":false,"linkedin":false},"popup":{},"code":{"copyButtons":true},"hide-element":{"elements":[".gitbook-link"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-comscore":{},"page-toc-button":{"maxTocDepth":2,"minTocSize":2},"back-to-top-button":{},"pageview-count":{},"flexible-alerts":{"danger":{"className":"danger","icon":"fa fa-ban","label":"Attention"},"note":{"className":"info","icon":"fa fa-info-circle","label":"Note"},"style":"callout","tip":{"className":"tip","icon":"fa fa-lightbulb-o","label":"Tip"},"warning":{"className":"warning","icon":"fa fa-exclamation-triangle","label":"Warning"}},"sharing":{"qq":false,"all":["douban","facebook","google","linkedin","twitter","weibo","qq","qzone","weibo"],"douban":false,"facebook":false,"weibo":true,"instapaper":false,"whatsapp":false,"hatenaBookmark":false,"twitter":false,"messenger":false,"line":true,"vk":false,"pocket":false,"google":true,"viber":false,"stumbleupon":false,"qzone":true,"linkedin":true},"edit-link":{"label":"编辑此页","base":"https://github.com/zeromicro/go-zero-doc/blob/master"},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","author":"松妹子","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"go-zero使用文档","language":"zh-hans","gitbook":"3.2.3"},"file":{"path":"api-grammar.md","mtime":"2021-04-10T07:21:07.992Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2021-04-10T07:22:08.598Z"},"basePath":".","book":{"language":""}});
        });
    </script>
</div>

        
    <script src="gitbook/gitbook.js"></script>
    <script src="gitbook/theme.js"></script>
    
        
        <script src="gitbook/gitbook-plugin-back-to-top-button/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-chapter-fold/chapter-fold.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-code/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-search-pro/jquery.mark.min.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-search-pro/search.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-github/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-splitter/splitter.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-sharing-plus/buttons.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-flexible-alerts/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-page-toc-button/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-pageview-count/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-hide-element/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-edit-link/plugin.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
        
    
        <script src="gitbook/gitbook-plugin-theme-comscore/test.js"></script>
        
    
    </body>
</html>