This repository was archived by the owner on Aug 13, 2025. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathindex.html
More file actions
284 lines (256 loc) · 17.4 KB
/
Copy pathindex.html
File metadata and controls
284 lines (256 loc) · 17.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Retrofit - 한글 문서</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A type-safe HTTP client for Android and Java">
<link href="static/bootstrap-combined.min.css" rel="stylesheet">
<link href="static/app.css" rel="stylesheet">
<link href="static/app-theme.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Roboto:400,300italic,100,100italic,300" rel="stylesheet" type="text/css">
<!--[if lt IE 9]><script src="static/html5shiv.min.js"></script><![endif]-->
</head>
<body data-target=".content-nav">
<header>
<div class="container">
<div class="row">
<div class="span5">
<h1>Retrofit</h1>
</div>
<div class="span7">
<menu>
<ul>
<li><a href="#download" class="menu download">Download <span class="version-tag">Latest</span></a></li>
<li><a href="http://github.com/square/retrofit" data-title="View GitHub Project" class="menu github"><img src="static/icon-github.png" alt="GitHub"/></a></li>
<li><a href="http://square.github.io/" data-title="Square Open Source Portal" class="menu square"><img src="static/icon-square.png" alt="Square"/></a></li>
</ul>
</menu>
</div>
</div>
</div>
</header>
<section id="subtitle">
<div class="container">
<div class="row">
<div class="span12">
<h2>A type-safe <strong>HTTP client</strong> for Android and Java<!-- and Samsung! --></h2>
</div>
</div>
</div>
</section>
<section id="body">
<div class="container">
<div class="row">
<div class="span9">
<section id="introduction">
<h3>소개</h3>
<p>Retrofit은 HTTP API를 자바 인터페이스 형태로 사용할 수 있습니다.</p>
<pre class="prettyprint">public interface GitHubService {
@GET("/users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}</pre>
<p><code>Retrofit</code> 클래스로 <code>GitHubService</code> 인터페이스를 구현하여 생성합니다.</p>
<pre class="prettyprint">Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.build();
GitHubService service = retrofit.create(GitHubService.class);</pre>
<p>각각의 <code>Call</code> 은 <code>GitHubService</code> 를 통하여 동기 또는 비동기하는 HTTP 요청을 원격 웹서버로 보낼 수 있습니다.</p>
<pre class="prettyprint">Call<List<Repo>> repos = service.listRepos("octocat");</pre>
<p>HTTP 요청은 어노테이션을 사용하여 명시합니다.</p>
<ul>
<li>URL 파라미터 치환과 쿼리 파라미터가 지원됩니다.</li>
<li>객체를 요청 body로 변환합니다. (예: JSON, protocol buffers)</li>
<li>멀티파트 요청 body와 파일 업로드가 가능합니다.</li>
</ul>
<p><em>Note:</em> This site is still in the process of being expanded for the new 2.0 APIs.</p>
</section>
<section id="api-declaration">
<h3>API 정의</h3>
<p>인터페이스의 어노테이션과 메소드 매개변수들은 요청을 어떻게 다룰지 지시합니다.</p>
<h4>요청 메소드</h4>
<p>모든 메소드들은 반드시 상대 URL과 요청 메소드를 명시하는 어노테이션을 가지고 있어야합니다. 기본으로 제공하는 요청 메소드 어노테이션은 다음과 같이 5개가 있습니다 : <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, <code>HEAD</code>.</p>
<pre class="prettyprint">@GET("/users/list")</pre>
<p>정적 쿼리 인자를 URL에 명시할 수도 있습니다.</p>
<pre class="prettyprint">@GET("/users/list?sort=desc")</pre>
<h4>URL 다루기</h4>
<p>요청 URL은 동적으로 부분 치환 가능하며, 이는 메소드 매개변수로 변경이 가능합니다. 부분 치환은 영문/숫자로 이루어진 문자열을 <code>{</code> 와 <code>}</code> 로 감싸 정의해줍니다. 반드시 이에 대응하는 <code>@Path</code> 를 메소드 매개변수에 명시해줘야합니다.</p>
<pre class="prettyprint">@GET("/group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);</pre>
<p>쿼리 매개변수도 명시 가능합니다.</p>
<pre class="prettyprint">@GET("/group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);</pre>
<p>보다 동적이며 다양한 쿼리 매개변수들은 <code>Map</code> 으로도 사용하실 수 있습니다.</p>
<pre class="prettyprint">@GET("/group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);</pre>
<h4>요청 본문</h4>
<p>HTTP 요청 본문에 객체를 <code>@Body</code> 어노테이션을 통해 명시가 가능합니다.</p>
<pre class="prettyprint">@POST("/users/new")
Call<User> createUser(@Body User user);</pre>
<p>이러한 객체들은 <code>Retrofit</code> 인스턴스에 추가된 컨버터에 따라 변환됩니다. 만약 해당 타입에 맞는 컨버터가 추가되어있지 않다면, <code>RequestBody</code> 만 사용하실 수 있습니다.</p>
<h4>Form-Encoded과 Multipart</h4>
<p>메소드는 form-encoded 데이터와 multipart 데이터 방식으로 정의 가능합니다.</p>
<p><code>@FormUrlEncoded</code> 어노테이션을 메소드에 명시하면 form-encoded 데이터로 전송 됩니다. 각 key-value pair의 key는 어노테이션 값에, value는 객체를 지시하는 <code>@Field</code> 어노테이션으로 매개변수에 명시하시면 됩니다.</p>
<pre class="prettyprint">@FormUrlEncoded
@POST("/user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);</pre>
<p>Multipart 요청은 <code>@Multipart</code> 어노테이션을 메소드에 명시하시면 됩니다. 각 파트들은 <code>@Part</code> 어노테이션으로 명시합니다.</p>
<pre class="prettyprint">@Multipart
@PUT("/user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);</pre>
<p>Multipart의 part는 <code>Retrofit</code> 의 컨버터나, <code>RequestBody</code> 를 통하여 직렬화(serialization) 가능한 객체를 사용하실 수 있습니다.</p>
<h4>헤더 다루기</h4>
<p>정적 헤더들은 <code>@Headers</code> 어노테이션을 통해 명시할 수 있습니다.</p>
<pre class="prettyprint">@Headers("Cache-Control: max-age=640000")
@GET("/widget/list")
Call<List<Widget>> widgetList();</pre>
<pre class="prettyprint">@Headers({
"Accept: application/vnd.github.v3.full+json",
"User-Agent: Retrofit-Sample-App"
})
@GET("/users/{username}")
Call<User> getUser(@Path("username") String username);</pre>
<p>참고하실 점은, 헤더들은 이름에 기준하여 각각의 값을 덮어씌우지 않습니다. 동일한 이름의 헤더를 추가한다면 모든 헤더들은 동일한 이름으로 모두 요청에 추가됩니다.</p>
<p>동적인 헤더는 <code>@Header</code> 어노테이션을 통해 명시 가능합니다. 반드시 이에 대응하는 <code>@Header</code> 어노테이션을 매개변수에 명시해야합니다. 만약 값이 null이라면 해당 헤더는 추가되지않습니다. 아니라면, 매개변수 객체의 <code>toString</code> 메소드를 호출하여 반환된 값을 헤더의 값으로 추가합니다.</p>
<pre class="prettyprint">@GET("/user")
Call<User> getUser(@Header("Authorization") String authorization)</pre>
<p>헤더를 모든 요청마다 추가하셔야 한다면 <a href="https://github.com/square/okhttp/wiki/Interceptors">OkHttp interceptor</a> 를 사용하십시요.</p>
<h4>동기 vs. 비동기</h4>
<p><code>Call</code> 인스턴스는 동기 혹은 비동기로 요청 실행이 가능합니다. 각 인스턴스들은 동기 혹은 비동기중 한가지 방식만 사용가능합니다, 하지만 <code>clone()</code> 메소드를 통해 새 인스턴스를 생성하시면 이전과 다른 방식을 사용 가능합니다.</p>
<p>안드로이드에서의 콜백들은 메인 스레드에서 실행됩니다. JVM에서는, HTTP 요청을 호출한 스레드와 동일한 스레드에서 콜백들이 실행됩니다.</p>
</section>
<section id="restadapter-configuration">
<h3>Retrofit 설정</h3>
<p><code>Retrofit</code> 은 API 인터페이스를 호출 가능한 객체로 바꿔줍니다. 기본적으로 Retrofit은 실행중인 플랫폼에 최적화된 설정을 제공하지만, 사용자정의도 가능합니다.</p>
<h4>컨버터</h4>
<p>기본적으로, Retrofit은 HTTP 요청 본문을 OkHttp의 <code>ResponseBody</code> 형식과 <code>@Body</code> 에 이용하는 <code>RequestBody</code> 타입만 역직렬화(deserialization) 할 수 있습니다.</p>
<p>컨버터들은 이외의 형식들을 변환해주는 역할을 합니다. 아래에 많이 사용하고 편리한 자사의 컨버터 6개의 라이브러리들을 사용하실 수 있습니다.</p>
<ul>
<li><a href="https://github.com/google/gson">Gson</a>: <code>com.squareup.retrofit:converter-gson</code></li>
<li><a href="http://wiki.fasterxml.com/JacksonHome">Jackson</a>: <code>com.squareup.retrofit:converter-jackson</code></li>
<li><a href="https://github.com/square/moshi/">Moshi</a>: <code>com.squareup.retrofit:converter-moshi</code></li>
<li><a href="https://developers.google.com/protocol-buffers/">Protobuf</a>: <code>com.squareup.retrofit:converter-protobuf</code></li>
<li><a href="https://github.com/square/wire">Wire</a>: <code>com.squareup.retrofit:converter-wire</code></li>
<li><a href="http://simple.sourceforge.net/">Simple XML</a>: <code>com.squareup.retrofit:converter-simplexml</code></li>
</ul>
<p>그 예로, Gson을 사용하는 <code>GitHubService</code> 인터페이스가 Gson을 역직렬화가 가능하게 <code>GsonConverterFactory</code> 클래스를 통해 컨버터를 추가하는 예제입니다.</p>
<pre class="prettyprint">Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
GitHubService service = retrofit.create(GitHubService.class);</pre>
<h4>사용자정의 컨버터</h4>
<p>만약 API와 통신하는데 Retrofit이 지원하지 않는 형식(e.g. YAML, txt, custom format) 이거나 현재 사용가능한 형식이지만 다른 라이브러리를 통해 구현하시길 원하신다면, 쉽게 나만의 컨버터를 만들 수 있습니다. <a href="https://github.com/square/retrofit/blob/master/retrofit/src/main/java/retrofit/Converter.java"><code>Converter.Factory</code> 클래스</a> 를 상속하여 만드시고, 이를 Retrofit 객체를 만드실때 추가하시면됩니다.</p>
</section>
<section id="download">
<h3>다운로드</h3>
<p><a href="https://search.maven.org/remote_content?g=com.squareup.retrofit2&a=retrofit&v=LATEST" class="dl version-href">↓ <span class="version-tag">Latest</span> JAR</a></p>
<p>Retrofit의 소스코드, 예제 그리고 이 문서의 원본이 필요하시면 <a href="http://github.com/square/retrofit">GitHub</a>를 방문하십시요.</p>
<h4>Maven</h4>
<pre class="prettyprint"><dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version><span class="version pln"><em>(insert latest version)</em></span></version>
</dependency></pre>
<h4>Gradle</h4>
<pre class="prettyprint">
compile 'com.squareup.retrofit2:retrofit:<span class="version pln"><em>(insert latest version)</em></span>'
</pre>
<p>Retrofit은 Java 7 이상, Android 2.3 이상에서만 사용가능합니다.</p>
<h4>ProGuard</h4>
<p>만약 프로젝트가 Proguard를 사용하시면 아래 내용을 설정에 추가하십시요:</p>
<pre class="prettyprint">
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions
</pre>
</section>
<section id="contributing">
<h3>Contributing</h3>
<p>If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request.</p>
<p>When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also make sure your code compiles by running <code>mvn clean verify</code>.</p>
<p>Before your code can be accepted into the project you must also sign the <a href="http://squ.re/sign-the-cla">Individual Contributor License Agreement (CLA)</a>.</p>
</section>
<section id="license">
<h3>License</h3>
<pre>Copyright 2013 Square, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</pre>
</section>
<section>
<h3>번역하기</h3>
<p>이 문서는 Retrofit의 영문 문서를 한국어로 번역한 문서입니다.</p>
<p>번역에 문제가 있으면 언제나 <a href="https://github.com/devflow/retrofit-kr">Github</a>를 통해 의견을 남겨주세요.</p>
</section>
</div>
<div class="span3">
<div class="content-nav" data-spy="affix" data-offset-top="80">
<ul class="nav nav-tabs nav-stacked primary">
<li><a href="#introduction">소개</a></li>
<li><a href="#api-declaration">API 정의</a></li>
<li><a href="#restadapter-configuration">Retrofit 설정</a></li>
<li><a href="#download">다운로드</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ul>
<ul class="nav nav-pills nav-stacked secondary">
<li><a href="http://square.github.io/retrofit/2.x/retrofit/">Javadoc</a></li>
<li><a href="http://stackoverflow.com/questions/tagged/retrofit?sort=active">StackOverflow</a></li>
</ul>
</div>
</div>
</div>
<div class="row">
<div class="span12 logo">
<a href="https://squareup.com"><img src="static/logo-square.png" alt="Square, Inc."/></a>
</div>
</div>
</div>
</section>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="static/bootstrap.min.js"></script>
<script src="static/jquery.smooth-scroll.min.js"></script>
<script src="static/jquery-maven-artifact.min.js"></script>
<script src="static/prettify.js"></script>
<script type="text/javascript">
$(function() {
// Syntax highlight code blocks.
prettyPrint();
// Spy on scroll position for real-time updating of current section.
$('body').scrollspy();
// Use smooth-scroll for internal links.
$('a').smoothScroll();
// Enable tooltips on the header nav image items.
$('.menu').tooltip({
placement: 'bottom',
trigger: 'hover',
container: 'body',
delay: {
show: 500,
hide: 0
}
});
// Look up the latest version of the library.
$.fn.artifactVersion('com.squareup.retrofit2', 'retrofit', function(version, url) {
$('.version').text(version);
$('.version-tag').text('v' + version);
$('.version-href').attr('href', url);
});
});
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-40704740-4', 'github.io');
ga('send', 'pageview');
</script>
</body>
</html>