Closure Compilerを使う!

Closure Compiler Service API:リファレンス

最終更新:

aias-closurecompiler

- view
管理者のみ編集可

トップページ > Closure Compiler Service API >

Closure Compiler Service API:リファレンス

このページでは、Closure Comiler Service APIのインターフェース仕様について詳細に説明します。APIの使用方法についてはこちらを参照してください。

コンパイルされたコードやAPIからの様々な情報を取得するためには、HTTP POSTリクエストを下記のURLに送る必要があります。

リクエストボディは「必須リクエストパラメータ」に列挙されたパラメータを必ず含んでいなければなりません。また「省略可能なリクエストパラメータ」に列挙されたパラメータを含めることもできます。

もしサーバがリクエストの処理に失敗した場合には、サーバエラーメッセージが返却されます。それらのメッセージについては「サーバエラーメッセージ」で説明されています。

  • このページは公式サイトのこちらを元に作成しました。

目次:

必須リクエストパラメータ

js_code

コンパイルするJavaScriptコードをパラメータの値として直接指定します。リクエストにはこのパラメータかcode_urlパラメータを少なくとも1つ以上含んでいなければなりません。両方指定することも可能です。 js_code パラメータを複数指定することもできます。

code_url

コンパイルするJavaScriptコードを内容にもつファイルのURLを指定します。リクエストにはこのパラメータかjs_codeパラメータを少なくとも1つ以上含んでいなければなりません。両方指定することも可能です。複数の入力ファイルを指定するため、リクエストには複数の code_url パラメータを含めることができます。

ファイルのURLはWEBからアクセス可能な場所でなければならない点に注意してください。 code_url パラメータの使用方法については、こちらでも詳しく説明しています。

compilation_level

JavaScriptに適用する圧縮と最適化の度合い(コンパイルレベル)を指定します。以下の3つのレベルがあります:

  • WHITESPACE_ONLY

    JavaScriptから空白・改行とコメントだけを削除します。

  • SIMPLE_OPTIMIZATIONS

    圧縮と最適化を実行しますが、ローカル変数のみをリネームし、コンパイルされたコードとそれ以外のコードとの連携を妨げません。

  • ADVANCED_OPTIMIZATIONS

    グローバル領域を含むシンボルのリネームを行い、最高レベルの圧縮度を実現します。 ADVANCED_OPTIMIZATIONS レベルを使用する場合、外部のシンボルとの参照関係を維持するために追加の手順が必要となる可能性があります。詳しくはこちらを参照してください。

各コンパイルレベルで入力コードに求められるコーディングルールについては、こちらで詳しく説明されています。

output_format

Closure Compilerサービスの出力フォーマットを指定します。指定可能なフォーマットは以下の3つです:

  • xml

    処理結果をXML形式で返却します。出力されるXMLは以下のような形式になります:

     <compilationResult>
       <compiledCode>var a="hello";alert(a);</compiledCode>
       <statistics>
         <originalSize>98</originalSize>
         <compressedSize>35</compressedSize>
         <compileTime>0</compileTime>
       </statistics>
     </compilationResult>

    compiledCode 要素の内容はClosure Compilerが生成した圧縮済みのJavaScriptコードです。この要素はoutput_infoパラメータの値に compiled_code が指定されたときのみ出力されます。同様に、 statistics 要素は output_info パラメータの値に statistics が指定されたときのみ出力されます。

    output_info パラメータの値に warnings が指定されCompilerが警告を生成した場合、出力結果には warning 要素が含まれます:

     <compilationResult>
       ...
       <warnings>
         <warning type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3" line="delete 1;">warning 1</warning>
         <warning type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="delete 1;">warning 2 </warning>
       </warnings>
       ...
     </compilationResult>

    output_info パラメータの値に errors が指定され、入力コードが文法エラーやその他コンパイル処理を妨害するような問題を含んでいた場合、Closure Compilerは errors 要素を出力します。 errors 要素は以下のようなものです:

     <compilationResult>
       ...
       <errors>
         <error type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3" line="var x=-'hello';">error 1 </error>
         <error type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="var x=-'hello'">error 2 </error>
       </errors>
       ...
     </compilationResult>

    error 要素と warning 要素の file line col 属性はClosure Compilerがそのエラーに遭遇した位置を示しています。

    もしClosure Compilerが処理を停止させるようなエラーに見舞われた場合、以下のような出力結果が返却されます。このタイプのエラーは、JavaScriptコードの内容ではなくリクエストそのものに問題があることを示しています。詳しくはこちらを参照してください:

     <compilationResult>
       <serverErrors>
         <error code="1">Over quota</error>
       </serverErrors>
     </compilationResult>

  • json

    処理結果をJSON(JavaScript Object Notation)形式の文字列で返却します。この文字列をJavaScriptとして評価すると、1個のJavaScriptオブジェクトが得られます。出力されるJSONデータは以下のような形式です:

    {
      "compiledCode":/* raw code here */,
      "errors": [
        {"charno":4321,
         "error":"ERROR: You failed.",
         "lineno":1234,
         "file":"default.js",
         "type":"ERROR_TYPE",
         "line":"var x=-'hello';"}
      ],
      "warnings": [
        {"charno":4321,
         "lineno":1234,
         "file":"default.js",
         "type":"ERROR_TYPE",
         "warning":"Warning: You did something wrong!",
         "line":"delete 1;"}
      ],
      "serverErrors":[
        {"code":123,"error":"Over quota"}
      ],
      "statistics":{
        "originalSize":10,
        "compressedSize":3000,
        "compileTime":10
      }
    }

    JSON形式とXML形式はよく似ています:XMLの各タグはJSONオブジェクト内の同名のプロパティに相当します。

  • text

    text フォーマットを指定すると、タグやJSONブラケットを取り除いたシンプルなテキスト形式の出力結果が返却されます。

output_info

Compilerから取得するデータの種類を指定します。指定できるのは以下の4種類です:

  • compiled_code

    入力されたJavaScriptコードを圧縮・最適化したものです。

  • warnings

    JavaScript内のバグの可能性を警告するメッセージです。

  • errors

    JavaScript内の文法エラーやその他のエラーを示すメッセージです。

  • statistics

    Closure Compilerが行った圧縮処理の達成度に関する情報です。出力形式がXMLの場合、以下のフォーマットの統計情報が返却されます:

     <compilationResult>
       ...
       <statistics>
         <firstStatisticName>24</firstStatisticName>
         <secondStatisticName>15</secondStatisticName>
       </statistics>
     </compilationResult>

省略可能なリクエストパラメータ

js_externs

js_externs パラメータはコンパイルされるコードが使用している外部プログラム内のシンボル名をリネームから保護するために使用します。このパラメータの値にはリネームされたくない関数やその他のシンボルを宣言するJavaScriptコードを指定します。このパラメータが効果をもつのはcompilation_levelパラメータの値が ADVANCED_OPTIMIZATIONS の場合のみです。詳しくは「extern宣言」を参照してください。

externs_url

externs_url パラメータはコンパイルされるコードが使用している外部プログラム内のシンボル名をリネームから保護するために使用します。このパラメータにはリネームされたくない関数やその他のシンボルを宣言するJavaScriptコードが記述されたファイルのURLを指定します。ファイル内に宣言されたシンボルはjs_externsパラメータに直接列挙された場合と全く同じ方法で保護されます。このパラメータが効果をもつのはcompilation_levelパラメータの値が ADVANCED_OPTIMIZATIONS の場合のみです。詳しくは「extern宣言」を参照してください。

リクエスト内に複数の externs_url パラメータを定義できます。

exclude_default_externs

Closure Compilerは document オブジェクトやそのメソッドのような標準的なシンボルを宣言した定義情報を持っており、デフォルトではそれを使用してシンボル名の保護を行います。もしこれらの標準的なextern宣言を使いたくない場合は、このパラメータにtrueを設定してリクエストに含めてください。デフォルトのextern宣言に関する詳細はこちらを参照してください。

output_file_name

このパラメータを指定すると、Closure Compilerはコンパイルされたコードをサーバ上に1時間キャッシュし、特別なURLを通してそれを利用可能にします。ファイルがキャッシュされている間、このURLにアクセスしコンパイルされたコードをテストすることができます。URLは以下のような形式です:

http://closure-compiler.appspot.com/code/bf067f356d510e1c7b81347eb84f65d2/[output_file_nameの値]

formatting

出力されるコンパイル済みJavaScriptコードの整形方式を指定します。このパラメータは pretty_print または print_input_delimiter のどちらかの値をとりますが、同一のリクエスト内に2つの formatting パラメータを含めれば、これらを同時に指定することが可能です。 pretty_print print_input_delimiter は整形方法のそれぞれ異なる側面に関する指示であるため、重複しても互いに影響しあうことがありません。

  • pretty_print

    リクエストが pretty_print を値にもつ formatting パラメータを含む場合、Closure Compilerは人間が読み易くなるよう出力コードに改行とインデントを付加します。以下にその例を示します:

    function hello(a) {
      alert("Hello, " + a)
    }
    hello("New user");

    pretty_print がない場合は次のようになります。

    function hello(a){alert("Hello, "+a)}hello("New user");

  • print_input_delimiter

    リクエストが print_input_delimiter を値にもつ formatting パラメータを含む場合、Closure Compilerは各入力ファイルの範囲を示す文字列を出力コード内に付加します。例えば2つのファイルを一緒にコンパイルした場合、出力は次のようになります。

    // Input 0
    alert("hi");
    // Input 1
    alert("bye");

    ファイル間の境界を表す区切り文字としてClosure Compilerは「 // Input X 」を挿入します。これらの区切り文字はコメントであり、JavaScriptの動作を妨げない点に注意してください。

    code_urlパラメータによって与えられた入力ファイルは、出力コード内で各ファイルに対応するセクションに区切られます。一方js_codeパラメータによって与えられた入力コードは、全ての js_code パラメータの値を結合したものが1つのセクションにまとめられます。入力ファイルの区切りには、例えば各ファイルのうちコードサイズの圧縮に最も貢献しているものの把握を助けるというような用途が考えられます。

use_closure_library

use_closure_library パラメータを true に設定すると、compilerはソース内の goog.require() を探し出し、そのステートメントが要求しているClosure Libraryのコードを出力に追加します。また、Closure Libraryのコードのために特に設計された最適化を実行します。Closure Libraryに関する詳細はClosure Library documentationを参照してください。 goog.require() 関数に関する詳細はFinding Your Way around the Closure Libraryを参照してください。

use_closure_library パラメータのデフォルト値は false です。

warning_level

コード内の問題になりそうな箇所に関する情報の出力量を指定します。 warning_level パラメータはoutput_infoパラメータの値に warning が一緒に指定されている場合のみ有効です。警告レベルには以下の3種類があります:

  • QUIET

    現在のコンパイルでのcompilation_levelに基づく最適化パスで生成された文法エラーと警告のみを出力します。

  • DEFAULT

    最適化パスで生成された文法エラーと警告に加え、最終的に選択されたコードチェックパスで生成された警告を出力します。 warning_level パラメータのデフォルト値です。

  • VERBOSE

    最適化パスで生成された文法エラーと警告に加え、実行された全てのコードチェックパスで生成された警告を出力します。

サーバエラーメッセージ

サーバがリクエストの処理に失敗した場合、下表に示すサーバエラーメッセージのうちのいずれかが返却されます。これらのエラーはCompilerが生成するエラーや警告とは異なるものである点に注意してください。Compilerが生成するエラーや警告はJavaScript内で見つかった問題を表しますが、サーバエラーのメッセージはリクエストそのもののエラーによりCompilerがコードを全く処理出来ないことを示しています。

  • コードの内容が原因で発生するエラーと警告については、こちらを参照してください。

エラーコード

メッセージ 意味
2 Unknown output mode. output_formatパラメータの値が xml json text 以外です。
4 Unknown compression level. compilation_levelパラメータの値が WHITESPACE_ONLY SIMPLE_OPTIMIZATIONS ADVANCED_OPTIMIZATIONS 以外です。
8 POST data too large. APIに送信されたデータのサイズが200,000バイトを超えています。Closure Compiler Service UIとAPIではサービスとの通信にHTTP-POSTリクエストを使用しますが、その際リクエストデータの合計が200,000バイトを超えてはなりません。
APIでは、この制限はリクエストパラメータに設定された全てのテキストの合計サイズに適用されます。UIでは、この制限はソースコードと @code_url のようなコンパイルオプションを合わせたものに適用されます。
もしリクエストが大きすぎた場合はソースコードをファイルに分離した上でそれをcode_urlパラメータで参照するようにするか、ローカルマシン上でClosure Compiler Applicationを使用してください。
9 File too large. コードの総量が1,024,000バイトを超えています。コードの総量とは、全てのcode_urlに指定されたファイル、全てのexterns_urlに指定されたファイル、全てのjs_codejs_externsに指定されたコードの合計を指します。
10 Cannot retrieve content from URL. このエラーはAPIがcode_urlパラメータで指定されたJavaScriptファイルまたはexterns_urlパラメータで指定されたexternファイルを取得できなかった場合に発生します。URLが正しいか、またファイルの参照を許可するように権限が設定されているかを確認してください。
12 URL is not formed properly. code_urlパラメータまたはexterns_urlパラメータに指定されたURLが不正な形式であることを表します。
13 No output information to produce, yet compilation was requested. output_infoパラメータが指定されていません。
14 Unknown output_info value output_infoパラメータの値が compiled_code warnings statistics 以外です。
16 Unknown warning level warning_levelパラメータの値が QUIET DEFAULT VERBOSE 以外です。
17 Unknown formatting option. formattingパラメータの値が pretty_print print_input_delimiter 以外です。
18 Unknown parameter in HTTP request 定義されていないパラメータが含まれています。
19 Illegal value for output_file_name 出力ファイル名が1文字の数字、文字、ドット、アンダースコア、ダッシュだけからなっているか、または2つの連続したドット(..)を含んでいます。
22 Too many compiles performed recently. Try again later. このマシンから送信されているコンパイルリクエストが多すぎます。コンパイルの実行が可能になるには1時間必要です。
23 Compiler exception (with backtrace) Compilerがクラッシュしました。エラーテキストにはGoogleのデバッグ作業の助けになる情報が含まれています。
24 Unsupported input resource type リソースタイプが「http:」でなかったため、入力ファイルを取得できませんでした。

目安箱バナー